tutorial-gen

LangGraph multi-agent pipeline that monitors Claude Code's CHANGELOG.md and generates validated tutorials for new features.

Architecture

A supervisor-subagent pattern built on LangGraph:

fetch_changelog → diff_features → [feature loop]
                                       │
                                   supervisor
                                   ╱   │   ╲
                          researcher  writer  script_generator
                                              │
                                          validator ↔ script_fixer
                                              │
                                         save_tutorial → next feature

Components

Layer	Files	Purpose
State	state.py	PipelineState TypedDict with reducer annotations
Graph	graph.py	StateGraph assembly, routing helpers, conditional edges
Agents	agents/supervisor.py	Routes work via structured output (RouteDecision)
	agents/researcher.py	Classifies feature type, gathers context
	agents/writer.py	Generates tutorial markdown
	agents/script_generator.py	Creates executable demo scripts
	agents/validator.py	Runs scripts in sandboxed subprocess
	agents/script_fixer.py	Repairs scripts that fail validation
Nodes	nodes/fetch.py	Fetches CHANGELOG.md from GitHub
	nodes/diff.py	Parses changelog, filters already-processed features
	nodes/save.py	Writes tutorial files, updates DB
DB	db.py	SQLite tracking for processed features
CLI	cli.py	Click-based CLI (tutgen run/status/list)

Setup

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Required environment variables (.env or exported):

ANTHROPIC_API_KEY=sk-ant-...

Usage

# Full pipeline — fetch changelog, generate tutorials for all new features
tutgen run

# Limit to N features
tutgen run --limit 3

# Preview what would be generated (no LLM calls)
tutgen run --dry-run

# Check processing status
tutgen status

# List generated tutorials
tutgen list

Output is written to tutorials/<date>-<slug>/ with tutorial.md and demo.sh.

Generated Script Patterns

The pipeline generates scripts that mirror realistic Claude Code usage:

• Session chaining (primary) — captures session_id via --output-format json, then uses --resume for multi-step workflows
• Slash commands (/simplify, /cost, etc.) — demonstrated via session chaining since they are interactive commands used inside Claude sessions, not standalone CLI args
• File-based workflows — creates project files, then uses session chaining for iterative work
• Simple one-shots — claude -p for standalone demos only

Testing

pytest tests/ -v

42 tests covering all agents (mocked LLM), nodes, graph construction, routing, and save logic.

Project Structure

src/tutorial_gen/
├── agents/           # LLM-powered subagents
│   ├── __init__.py   # Shared extract_script utility
│   ├── supervisor.py
│   ├── researcher.py
│   ├── writer.py
│   ├── script_generator.py
│   ├── script_fixer.py
│   └── validator.py
├── nodes/            # Non-LLM processing nodes
│   ├── fetch.py
│   ├── diff.py
│   └── save.py
├── prompts/          # Prompt templates per agent
├── state.py          # PipelineState schema
├── graph.py          # StateGraph construction
├── db.py             # SQLite feature tracking
└── cli.py            # CLI entry point
tests/
├── test_agents.py
├── test_diff.py
├── test_fetch.py
├── test_graph.py
├── test_save.py
├── test_supervisor.py
└── test_validate.py