stevio-tutorial

A Claude Code plugin that turns any finished project into a step-by-step tutorial with exercises.

How It Works

You have a working project on a reference branch. This plugin analyzes it and generates a structured tutorial where readers build the project from scratch, chapter by chapter.

Any small-to-medium project works as a reference — including purely vibe-coded ones. In fact, that's the original idea: take something you built with AI assistance and learn how it actually works by rebuilding it step by step.

The tutorial follows a "learning book" pedagogy:

• WHY before WHAT — explain motivation before showing the approach
• Skeleton code with exercises — readers implement the logic themselves
• Incremental verification — each chapter produces something testable
• Adaptive planning — the tutorial adapts when readers take different approaches

Commands

/stevio-init

Initialize a tutorial from a reference implementation.

• Analyzes the codebase and triages files (pedagogical, teach-to-acquire, ignore)
• Extracts a mechanical symbol inventory using tree-sitter
• Proposes a chapter outline with learning objectives and dependency ordering
• Validates the plan against the inventory (coverage, ordering, completeness)
• Creates .tutorial/ with plan.md, progress.md, next-chapter.md, validators, and tools

/stevio-next

Write the next tutorial chapter.

• Reads plan.md, progress.md, and next-chapter.md for context
• Loads only files relevant to this chapter's symbols and dependencies (selective context loading)
• Writes the chapter with exercises, explanations, and verification steps
• Runs a self-review (grammar, code quality, reference firewall check)

/stevio-done

Complete the current chapter.

• Verifies the reader's code works (builds, tests pass)
• Mechanically validates symbol implementations via tree-sitter
• Coaches the reader if something is broken
• Detects divergence from the reference and adapts future chapters
• Generates next-chapter.md for the upcoming chapter with inventory metadata

/stevio-help

Get coaching on a specific exercise without spoiling the answer.

• Format: /stevio-help E3.2 Why does this need to return an error?
• Provides conceptual explanations, hints, and API pointers
• Never reveals the reference implementation

Workflow

1. Build your project (any language/framework)
2. /stevio-init          → analyzes codebase, creates plan
3. Create tutorial branch, commit .tutorial/, remove source files
4. /stevio-next          → writes Chapter 01
5. Reader implements exercises
6. /stevio-done          → verifies, closes chapter
7. Repeat 4-6 until complete

Installation

Load the plugin by pointing Claude Code at the plugin directory:

claude --plugin-dir /path/to/stevio-claude-tutorial

Generated Files

The plugin creates these files in your project:

.tutorial/
├── plan.md                    # Chapter outline with status markers
├── progress.md                # Compact chapter summaries
├── next-chapter.md            # Teaching brief for upcoming chapter
├── reference-inventory.json   # Tree-sitter symbol inventory (immutable)
├── validators/                # Language-specific validation scripts
│   └── validate-*.sh
└── tools/                     # Tree-sitter validation tools
    ├── run-tool.sh
    ├── extract-inventory.py
    ├── validate-plan.py
    ├── validate-user-progress.py
    └── requirements.txt

docs/tutorials/
├── 01-project-setup.md        # Chapter files
├── 02-build-system.md
└── ...

Requirements

• Claude Code CLI
• A git repository with a working implementation
• The implementation should build and run successfully
• Python 3 (tree-sitter dependencies are installed automatically — uses uv if available, otherwise creates a local .venv)
• A small-to-medium project works best (the kind you can hold in your head once you understand it)
• Vibe-coded projects work great — learning what the AI generated is the whole point

Sandbox Mode

The tree-sitter tools need to install Python packages (into a local .venv or via uv). This requires network access and write permissions that Claude Code's default sandbox blocks.

To use this plugin, you need to either:

1. Allowlist the tools directory for writes in your sandbox settings, or
2. Pre-install dependencies before running /stevio-init:

   pip install tree-sitter tree-sitter-language-pack

3. Use uv — if uv is installed and its cache is populated, run-tool.sh works without network access on repeat runs.

Supported Languages

The tree-sitter symbol extraction supports: Zig, Go, Rust, Python, Java, Kotlin, TypeScript, JavaScript, C, C++, Swift, and Objective-C.

License

MIT