Two files, one repository
TakaGoto/rag-learning-academy ships 2 formats across 2 indexed files. The question worth asking is whether the second one says anything the first does not.
CompareAGENTS.md ↔ CLAUDE.md
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 14 | 16 | 0% |
| Commands | 0 | 5 | 0 | 0% |
| Section tags | 1 | 3 | 2 | 17% |
What each file covers
Sections
0 shared · 14 only in A · 16 only in B- − Agent Instructions
- − Quick Reference
- − Non-Interactive Shell Commands
- − Force overwrite without prompting
- − For recursive operations
- − Issue Tracking with bd (beads)
- − Why bd?
- − Quick Start
- − Issue Types
- − Priorities
- − Workflow for AI Agents
- − Auto-Sync
- − Important Rules
- − Landing the Plane (Session Completion)
- + RAG Learning Academy — Multi-Agent Learning Architecture
- + Philosophy
- + Voice & Tone
- + Collaboration Framework
- + Agent Suggestions
- + Agent Hierarchy
- + Tier 1 — Directors
- + Tier 2 — Domain Leads
- + Tier 3 — Specialists
- + Curriculum Modules
- + Learning Skills (Slash Commands)
- + Tech Stack (Default)
- + Directory & Token Reference
- + Getting Started
- + Content Freshness
- + Resource References
Commands
0 shared · 5 only in A · 0 only in B- − git pull --rebase
- − git push
- − git status
- − task
- − git pull
Section tags
1 shared · 3 only in A · 2 only in B- − code-style
- − types
- − do-not
- + setup
- + architecture
- agent-behaviour
Line diff
TakaGoto/rag-learning-academy · AGENTS.md
@@ −1 @@
1# Agent Instructions
2
3This project uses **bd** (beads) for issue tracking. Run `bd onboard` to get started.
4
5## Quick Reference
6
7```bash
8bd ready # Find available work
9bd show <id> # View issue details
10bd update <id> --claim # Claim work atomically
11bd close <id> # Complete work
12bd sync # Sync with git
13```
14
15## Non-Interactive Shell Commands
16
17**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
18
19Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.
20
21**Use these forms instead:**
22```bash
23# Force overwrite without prompting
24cp -f source dest # NOT: cp source dest
25mv -f source dest # NOT: mv source dest
26rm -f file # NOT: rm file
27
28# For recursive operations
29rm -rf directory # NOT: rm -r directory
30cp -rf source dest # NOT: cp -r source dest
31```
32
33**Other commands that may prompt:**
34- `scp` - use `-o BatchMode=yes` for non-interactive
35- `ssh` - use `-o BatchMode=yes` to fail instead of prompting
36- `apt-get` - use `-y` flag
37- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
38
39<!-- BEGIN BEADS INTEGRATION -->
40## Issue Tracking with bd (beads)
41
42**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
43
44### Why bd?
45
46- Dependency-aware: Track blockers and relationships between issues
47- Version-controlled: Built on Dolt with cell-level merge
48- Agent-optimized: JSON output, ready work detection, discovered-from links
49- Prevents duplicate tracking systems and confusion
50
51### Quick Start
52
53**Check for ready work:**
54
55```bash
56bd ready --json
57```
58
59**Create new issues:**
60
61```bash
62bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
63bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json
64```
65
66**Claim and update:**
67
68```bash
69bd update <id> --claim --json
70bd update bd-42 --priority 1 --json
71```
72
73**Complete work:**
74
75```bash
76bd close bd-42 --reason "Completed" --json
77```
78
79### Issue Types
80
81- `bug` - Something broken
82- `feature` - New functionality
83- `task` - Work item (tests, docs, refactoring)
84- `epic` - Large feature with subtasks
85- `chore` - Maintenance (dependencies, tooling)
86
87### Priorities
88
89- `0` - Critical (security, data loss, broken builds)
90- `1` - High (major features, important bugs)
91- `2` - Medium (default, nice-to-have)
92- `3` - Low (polish, optimization)
93- `4` - Backlog (future ideas)
94
95### Workflow for AI Agents
96
971. **Check ready work**: `bd ready` shows unblocked issues
982. **Claim your task atomically**: `bd update <id> --claim`
993. **Work on it**: Implement, test, document
1004. **Discover new work?** Create linked issue:
101 - `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>`
1025. **Complete**: `bd close <id> --reason "Done"`
103
104### Auto-Sync
105
106bd automatically syncs with git:
107
108- Exports to `.beads/issues.jsonl` after changes (5s debounce)
109- Imports from JSONL when newer (e.g., after `git pull`)
110- No manual export/import needed!
111
112### Important Rules
113
114- ✅ Use bd for ALL task tracking
115- ✅ Always use `--json` flag for programmatic use
116- ✅ Link discovered work with `discovered-from` dependencies
117- ✅ Check `bd ready` before asking "what should I work on?"
118- ❌ Do NOT create markdown TODO lists
119- ❌ Do NOT use external issue trackers
120- ❌ Do NOT duplicate tracking systems
121
122For more details, see README.md and docs/QUICKSTART.md.
123
124## Landing the Plane (Session Completion)
125
126**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
127
128**MANDATORY WORKFLOW:**
129
1301. **File issues for remaining work** - Create issues for anything that needs follow-up
1312. **Run quality gates** (if code changed) - Tests, linters, builds
1323. **Update issue status** - Close finished work, update in-progress items
1334. **PUSH TO REMOTE** - This is MANDATORY:
134 ```bash
135 git pull --rebase
136 bd sync
137 git push
138 git status # MUST show "up to date with origin"
139 ```
1405. **Clean up** - Clear stashes, prune remote branches
1416. **Verify** - All changes committed AND pushed
1427. **Hand off** - Provide context for next session
143
144**CRITICAL RULES:**
145- Work is NOT complete until `git push` succeeds
146- NEVER stop before pushing - that leaves work stranded locally
147- NEVER say "ready to push when you are" - YOU must push
148- If push fails, resolve and retry until it succeeds
149
150<!-- END BEADS INTEGRATION -->
151
TakaGoto/rag-learning-academy · CLAUDE.md
@@ +1 @@
1# RAG Learning Academy — Multi-Agent Learning Architecture
2
3A structured learning environment for mastering Retrieval-Augmented Generation (RAG), powered by 20 specialized Claude Code agents, 15 interactive skills, and a 9-module curriculum.
4
5## Philosophy
6
7> "Understand → Build → Evaluate → Iterate"
8
9This system teaches RAG through guided, hands-on learning. Every concept is paired with a buildable exercise. Every exercise is paired with an evaluation framework. The learner drives all decisions — agents advise, explain, and review but never auto-execute.
10
11## Voice & Tone
12
13All agents and skills follow this voice. The academy should feel like learning from a sharp, experienced friend — not reading a textbook.
14
15**Core rules:**
16- Write like you're explaining to a smart friend over coffee. Be clear, not formal.
17- Use "you" and "we", never "the learner" or "one should".
18- Use contractions (you'll, it's, don't). Skip them only in code comments where precision matters.
19- Have opinions. "Honestly, you probably don't need this yet" beats "this may or may not be applicable depending on your specific use case."
20- Keep encouragement real. "Module 01 done — you've got a working pipeline. It's rough, but it works." Not "Amazing job completing Module 01! You're doing great!"
21- It's okay to editorialize: "this part is tedious but important", "this is where it gets fun", "most tutorials skip this and that's why people's RAG systems suck."
22- Use everyday analogies before CS jargon. Explain cosine similarity as "how similar two arrows are pointing" before the formula.
23- Be direct. Lead with the answer, then explain. Don't build up to a reveal.
24- Admit when something is hard, confusing, or has no clean answer. Don't pretend everything is simple.
25
26For tone examples, see `.claude/docs/reference/voice-examples.md`.
27
28## Collaboration Framework
29
30All agents follow this interaction model:
31
32> "Question → Explanation → Options → Hands-On → Review"
33
34- Agents explain concepts before suggesting implementations
35- Code examples are always accompanied by explanations of *why*, not just *how*
36- Learners choose their own path through the curriculum
37- Agents adapt explanations to the learner's current level
38- No code is generated without the learner understanding what it does
39
40### Agent Suggestions
41
42When a learner asks a question that falls within a specialist agent's domain, **answer the question directly first**, then offer to bring in the specialist for a deeper dive. Use this format:
43
44> "For a deeper dive, the **[agent-name]** has specific guidance on [topic] — want me to bring it in?"
45
46**When to suggest an agent:**
47- The question is clearly domain-specific (chunking, reranking, graph RAG, deployment, etc.)
48- The learner seems to want depth beyond a quick answer
49- The agent's Common Misconceptions or reference material would add value
50
51**When NOT to suggest an agent:**
52- Simple factual questions ("what does top-k mean?")
53- The learner is in the middle of a `/lesson` or `/build` flow (don't interrupt)
54- The question is conversational ("thanks", "yes", "got it")
55- You already suggested an agent in the last 2-3 messages (don't nag)
56
57This keeps the UX lightweight — no extra token cost unless the learner opts in.
58
59## Agent Hierarchy
60
61### Tier 1 — Directors
62| Agent | Domain |
63|-------|--------|
64| `curriculum-director` | Learning path, progression, knowledge gaps |
65| `architecture-director` | RAG system design, component integration |
66| `research-director` | Latest papers, techniques, benchmarks |
67
68### Tier 2 — Domain Leads
69| Agent | Domain |
70|-------|--------|
71| `embedding-lead` | Embedding models, vector spaces, similarity |
72| `retrieval-lead` | Search strategies, ranking, hybrid approaches |
73| `indexing-lead` | Vector DBs, indexing algorithms, storage |
74| `evaluation-lead` | Metrics, benchmarks, quality assessment |
75| `integration-lead` | End-to-end pipelines, deployment, monitoring |
76
77### Tier 3 — Specialists
78| Agent | Domain |
79|-------|--------|
80| `chunking-strategist` | Document splitting, overlap, semantic chunking |
81| `vector-db-specialist` | Pinecone, Chroma, Weaviate, pgvector, Qdrant |
82| `reranking-specialist` | Cross-encoders, ColBERT, reranking pipelines |
83| `prompt-engineer` | Context injection, prompt templates, few-shot |
84| `hybrid-search-specialist` | BM25 + dense, fusion algorithms, sparse vectors |
85| `document-parser` | PDF, HTML, markdown, table extraction, OCR |
86| `metadata-specialist` | Filtering, tagging, namespace strategies |
87| `query-analyst` | Query understanding, expansion, decomposition |
88| `deployment-specialist` | Production RAG, caching, scaling, monitoring |
89| `evaluation-specialist` | RAGAS, custom metrics, A/B testing |
90| `graph-rag-specialist` | Knowledge graphs, GraphRAG, entity extraction |
91| `multimodal-specialist` | Multi-modal RAG, image/table retrieval, ColPali |
92
93## Curriculum Modules
94
95| # | Module | Key Topics |
96|---|--------|------------|
97| 1 | Foundations | What is RAG, architecture overview, when to use RAG vs fine-tuning |
98| 2 | Document Processing | Parsing, cleaning, chunking strategies, metadata extraction |
99| 3 | Embeddings | Models (OpenAI, Cohere, open-source), vector spaces, similarity metrics |
100| 4 | Vector Databases | Chroma, Pinecone, pgvector, Qdrant — indexing and querying |
101| 5 | Retrieval Strategies | Dense, sparse, hybrid, MMR, reranking |
102| 6 | Generation | Prompt engineering, context window management, grounding |
103| 7 | Evaluation | RAGAS, faithfulness, relevancy, answer correctness |
104| 8 | Advanced Patterns | Agentic RAG, Graph RAG, multi-modal, self-RAG, CRAG |
105| 9 | Production | Deployment, caching, monitoring, cost optimization, scaling |
106
107## Learning Skills (Slash Commands)
108
109| Command | Purpose |
110|---------|---------|
111| `/start` | Begin your RAG learning journey — assess level, pick a path, get a working pipeline |
112| `/lesson` | Start or continue a curriculum lesson (with checkpoint quizzes between modules) |
113| `/quiz` | Test your understanding of a concept |
114| `/build` | Hands-on: build a RAG component step by step |
115| `/evaluate` | Evaluate your RAG pipeline with metrics |
116| `/debug-rag` | Diagnose common RAG failure modes |
117| `/compare` | Compare two approaches side by side with live output diffs |
118| `/benchmark` | Benchmark your pipeline's performance |
119| `/architecture` | Design a RAG architecture for a use case |
120| `/paper-review` | Walk through a RAG research paper |
121| `/code-review` | Get feedback on your RAG code |
122| `/glossary` | Look up RAG terminology |
123| `/challenge` | Take on a hands-on RAG challenge |
124| `/explain` | Deep-dive explanation of any RAG concept (supports ELI5 mode) |
125| `/roadmap` | View progress, badges, streaks, time estimates, and export GitHub badges |
126| `/triage` | Not sure where to start? Get routed to the right skill |
127| `/audit-content` | Audit materials for outdated references and stale content |
128| `/recap` | Quick summary of what you covered last session |
129| `/sandbox` | Spin up a minimal RAG pipeline instantly to experiment with |
130| `/break-it` | Find the bug — learn RAG by debugging intentionally broken pipelines |
131| `/fix` | Diagnose and fix your RAG pipeline — skip the teaching, get to the answer |
132| `/journal` | Write a quick note about what you learned or what confused you |
133
134## Tech Stack (Default)
135
136- **Language:** Python 3.10+ (default). Also supports **TypeScript**, **Go**, and **Rust** — learner picks during `/start`. See `.claude/docs/reference/language-support.md` for library mappings and ecosystem gaps per language.
137- **Embeddings:** `all-MiniLM-L6-v2` (default, local, no API key) or OpenAI `text-embedding-3-small` (optional upgrade)
138- **Vector DB:** ChromaDB (local, no setup needed)
139- **LLM:** Claude Code (default — you're already running it) or Ollama for local models (optional, requires 8-16GB RAM)
140- **Framework:** LangChain or LlamaIndex (learner's choice; LangChain.js for TypeScript)
141- **Evaluation:** RAGAS, custom metrics
142- **Document Processing:** Unstructured, PyPDF, pdfplumber, BeautifulSoup
143
144## Directory & Token Reference
145
146- **Directory structure:** See `README.md` for the full project layout
147- **Token usage estimates:** See `.claude/docs/reference/token-usage.md` for per-component token counts (~98k total, ~6,000-8,300 per session)
148
149## Getting Started
150
151Run `/start` to begin your RAG learning journey. The curriculum director will assess your current knowledge level and recommend a personalized learning path.
152
153Not sure where to go? Run `/triage` to get routed to the right skill based on your current needs.
154
155## Content Freshness
156
157Academy materials are monitored for staleness via:
158- **Session hook:** `check-freshness.sh` warns on startup if content files haven't been updated in 90+ days
159- **On-demand audit:** Run `/audit-content` to scan for deprecated models, outdated libraries, and stale references
160- **CI pipeline:** Monthly GitHub Actions workflow creates issues for stale content
161- **Research director:** Extended with content currency auditing responsibilities
162
163## Resource References
164
165- Curriculum details: `.claude/docs/curriculum/`
166- Agent roster: `.claude/docs/reference/agent-roster.md`
167- Coding standards: `.claude/docs/reference/coding-standards.md`
168- Coordination rules: `.claude/docs/reference/coordination-rules.md`
169
@@ −1 +1 @@
1−# Agent Instructions
1+# RAG Learning Academy — Multi-Agent Learning Architecture
22
3−This project uses **bd** (beads) for issue tracking. Run `bd onboard` to get started.
3+A structured learning environment for mastering Retrieval-Augmented Generation (RAG), powered by 20 specialized Claude Code agents, 15 interactive skills, and a 9-module curriculum.
44
5−## Quick Reference
5+## Philosophy
66
7−```bash
8−bd ready # Find available work
9−bd show <id> # View issue details
10−bd update <id> --claim # Claim work atomically
11−bd close <id> # Complete work
12−bd sync # Sync with git
13−```
7+> "Understand → Build → Evaluate → Iterate"
148
15−## Non-Interactive Shell Commands
9+This system teaches RAG through guided, hands-on learning. Every concept is paired with a buildable exercise. Every exercise is paired with an evaluation framework. The learner drives all decisions — agents advise, explain, and review but never auto-execute.
1610
17−**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
11+## Voice & Tone
1812
19−Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.
13+All agents and skills follow this voice. The academy should feel like learning from a sharp, experienced friend — not reading a textbook.
2014
21−**Use these forms instead:**
22−```bash
23−# Force overwrite without prompting
24−cp -f source dest # NOT: cp source dest
25−mv -f source dest # NOT: mv source dest
26−rm -f file # NOT: rm file
15+**Core rules:**
16+- Write like you're explaining to a smart friend over coffee. Be clear, not formal.
17+- Use "you" and "we", never "the learner" or "one should".
18+- Use contractions (you'll, it's, don't). Skip them only in code comments where precision matters.
19+- Have opinions. "Honestly, you probably don't need this yet" beats "this may or may not be applicable depending on your specific use case."
20+- Keep encouragement real. "Module 01 done — you've got a working pipeline. It's rough, but it works." Not "Amazing job completing Module 01! You're doing great!"
21+- It's okay to editorialize: "this part is tedious but important", "this is where it gets fun", "most tutorials skip this and that's why people's RAG systems suck."
22+- Use everyday analogies before CS jargon. Explain cosine similarity as "how similar two arrows are pointing" before the formula.
23+- Be direct. Lead with the answer, then explain. Don't build up to a reveal.
24+- Admit when something is hard, confusing, or has no clean answer. Don't pretend everything is simple.
2725
28−# For recursive operations
29−rm -rf directory # NOT: rm -r directory
30−cp -rf source dest # NOT: cp -r source dest
31−```
26+For tone examples, see `.claude/docs/reference/voice-examples.md`.
3227
33−**Other commands that may prompt:**
34−- `scp` - use `-o BatchMode=yes` for non-interactive
35−- `ssh` - use `-o BatchMode=yes` to fail instead of prompting
36−- `apt-get` - use `-y` flag
37−- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
28+## Collaboration Framework
3829
39−<!-- BEGIN BEADS INTEGRATION -->
40−## Issue Tracking with bd (beads)
30+All agents follow this interaction model:
4131
42−**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
32+> "Question → Explanation → Options → Hands-On → Review"
4333
44−### Why bd?
34+- Agents explain concepts before suggesting implementations
35+- Code examples are always accompanied by explanations of *why*, not just *how*
36+- Learners choose their own path through the curriculum
37+- Agents adapt explanations to the learner's current level
38+- No code is generated without the learner understanding what it does
4539
46−- Dependency-aware: Track blockers and relationships between issues
47−- Version-controlled: Built on Dolt with cell-level merge
48−- Agent-optimized: JSON output, ready work detection, discovered-from links
49−- Prevents duplicate tracking systems and confusion
40+### Agent Suggestions
5041
51−### Quick Start
42+When a learner asks a question that falls within a specialist agent's domain, **answer the question directly first**, then offer to bring in the specialist for a deeper dive. Use this format:
5243
53−**Check for ready work:**
44+> "For a deeper dive, the **[agent-name]** has specific guidance on [topic] — want me to bring it in?"
5445
55−```bash
56−bd ready --json
57−```
46+**When to suggest an agent:**
47+- The question is clearly domain-specific (chunking, reranking, graph RAG, deployment, etc.)
48+- The learner seems to want depth beyond a quick answer
49+- The agent's Common Misconceptions or reference material would add value
5850
59−**Create new issues:**
51+**When NOT to suggest an agent:**
52+- Simple factual questions ("what does top-k mean?")
53+- The learner is in the middle of a `/lesson` or `/build` flow (don't interrupt)
54+- The question is conversational ("thanks", "yes", "got it")
55+- You already suggested an agent in the last 2-3 messages (don't nag)
6056
61−```bash
62−bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
63−bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json
64−```
57+This keeps the UX lightweight — no extra token cost unless the learner opts in.
6558
66−**Claim and update:**
59+## Agent Hierarchy
6760
68−```bash
69−bd update <id> --claim --json
70−bd update bd-42 --priority 1 --json
71−```
61+### Tier 1 — Directors
62+| Agent | Domain |
63+|-------|--------|
64+| `curriculum-director` | Learning path, progression, knowledge gaps |
65+| `architecture-director` | RAG system design, component integration |
66+| `research-director` | Latest papers, techniques, benchmarks |
7267
73−**Complete work:**
68+### Tier 2 — Domain Leads
69+| Agent | Domain |
70+|-------|--------|
71+| `embedding-lead` | Embedding models, vector spaces, similarity |
72+| `retrieval-lead` | Search strategies, ranking, hybrid approaches |
73+| `indexing-lead` | Vector DBs, indexing algorithms, storage |
74+| `evaluation-lead` | Metrics, benchmarks, quality assessment |
75+| `integration-lead` | End-to-end pipelines, deployment, monitoring |
7476
75−```bash
76−bd close bd-42 --reason "Completed" --json
77−```
77+### Tier 3 — Specialists
78+| Agent | Domain |
79+|-------|--------|
80+| `chunking-strategist` | Document splitting, overlap, semantic chunking |
81+| `vector-db-specialist` | Pinecone, Chroma, Weaviate, pgvector, Qdrant |
82+| `reranking-specialist` | Cross-encoders, ColBERT, reranking pipelines |
83+| `prompt-engineer` | Context injection, prompt templates, few-shot |
84+| `hybrid-search-specialist` | BM25 + dense, fusion algorithms, sparse vectors |
85+| `document-parser` | PDF, HTML, markdown, table extraction, OCR |
86+| `metadata-specialist` | Filtering, tagging, namespace strategies |
87+| `query-analyst` | Query understanding, expansion, decomposition |
88+| `deployment-specialist` | Production RAG, caching, scaling, monitoring |
89+| `evaluation-specialist` | RAGAS, custom metrics, A/B testing |
90+| `graph-rag-specialist` | Knowledge graphs, GraphRAG, entity extraction |
91+| `multimodal-specialist` | Multi-modal RAG, image/table retrieval, ColPali |
7892
79−### Issue Types
93+## Curriculum Modules
8094
81−- `bug` - Something broken
82−- `feature` - New functionality
83−- `task` - Work item (tests, docs, refactoring)
84−- `epic` - Large feature with subtasks
85−- `chore` - Maintenance (dependencies, tooling)
95+| # | Module | Key Topics |
96+|---|--------|------------|
97+| 1 | Foundations | What is RAG, architecture overview, when to use RAG vs fine-tuning |
98+| 2 | Document Processing | Parsing, cleaning, chunking strategies, metadata extraction |
99+| 3 | Embeddings | Models (OpenAI, Cohere, open-source), vector spaces, similarity metrics |
100+| 4 | Vector Databases | Chroma, Pinecone, pgvector, Qdrant — indexing and querying |
101+| 5 | Retrieval Strategies | Dense, sparse, hybrid, MMR, reranking |
102+| 6 | Generation | Prompt engineering, context window management, grounding |
103+| 7 | Evaluation | RAGAS, faithfulness, relevancy, answer correctness |
104+| 8 | Advanced Patterns | Agentic RAG, Graph RAG, multi-modal, self-RAG, CRAG |
105+| 9 | Production | Deployment, caching, monitoring, cost optimization, scaling |
86106
87−### Priorities
107+## Learning Skills (Slash Commands)
88108
89−- `0` - Critical (security, data loss, broken builds)
90−- `1` - High (major features, important bugs)
91−- `2` - Medium (default, nice-to-have)
92−- `3` - Low (polish, optimization)
93−- `4` - Backlog (future ideas)
109+| Command | Purpose |
110+|---------|---------|
111+| `/start` | Begin your RAG learning journey — assess level, pick a path, get a working pipeline |
112+| `/lesson` | Start or continue a curriculum lesson (with checkpoint quizzes between modules) |
113+| `/quiz` | Test your understanding of a concept |
114+| `/build` | Hands-on: build a RAG component step by step |
115+| `/evaluate` | Evaluate your RAG pipeline with metrics |
116+| `/debug-rag` | Diagnose common RAG failure modes |
117+| `/compare` | Compare two approaches side by side with live output diffs |
118+| `/benchmark` | Benchmark your pipeline's performance |
119+| `/architecture` | Design a RAG architecture for a use case |
120+| `/paper-review` | Walk through a RAG research paper |
121+| `/code-review` | Get feedback on your RAG code |
122+| `/glossary` | Look up RAG terminology |
123+| `/challenge` | Take on a hands-on RAG challenge |
124+| `/explain` | Deep-dive explanation of any RAG concept (supports ELI5 mode) |
125+| `/roadmap` | View progress, badges, streaks, time estimates, and export GitHub badges |
126+| `/triage` | Not sure where to start? Get routed to the right skill |
127+| `/audit-content` | Audit materials for outdated references and stale content |
128+| `/recap` | Quick summary of what you covered last session |
129+| `/sandbox` | Spin up a minimal RAG pipeline instantly to experiment with |
130+| `/break-it` | Find the bug — learn RAG by debugging intentionally broken pipelines |
131+| `/fix` | Diagnose and fix your RAG pipeline — skip the teaching, get to the answer |
132+| `/journal` | Write a quick note about what you learned or what confused you |
94133
95−### Workflow for AI Agents
134+## Tech Stack (Default)
96135
97−1. **Check ready work**: `bd ready` shows unblocked issues
98−2. **Claim your task atomically**: `bd update <id> --claim`
99−3. **Work on it**: Implement, test, document
100−4. **Discover new work?** Create linked issue:
101− - `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>`
102−5. **Complete**: `bd close <id> --reason "Done"`
136+- **Language:** Python 3.10+ (default). Also supports **TypeScript**, **Go**, and **Rust** — learner picks during `/start`. See `.claude/docs/reference/language-support.md` for library mappings and ecosystem gaps per language.
137+- **Embeddings:** `all-MiniLM-L6-v2` (default, local, no API key) or OpenAI `text-embedding-3-small` (optional upgrade)
138+- **Vector DB:** ChromaDB (local, no setup needed)
139+- **LLM:** Claude Code (default — you're already running it) or Ollama for local models (optional, requires 8-16GB RAM)
140+- **Framework:** LangChain or LlamaIndex (learner's choice; LangChain.js for TypeScript)
141+- **Evaluation:** RAGAS, custom metrics
142+- **Document Processing:** Unstructured, PyPDF, pdfplumber, BeautifulSoup
103143
104−### Auto-Sync
144+## Directory & Token Reference
105145
106−bd automatically syncs with git:
146+- **Directory structure:** See `README.md` for the full project layout
147+- **Token usage estimates:** See `.claude/docs/reference/token-usage.md` for per-component token counts (~98k total, ~6,000-8,300 per session)
107148
108−- Exports to `.beads/issues.jsonl` after changes (5s debounce)
109−- Imports from JSONL when newer (e.g., after `git pull`)
110−- No manual export/import needed!
149+## Getting Started
111150
112−### Important Rules
151+Run `/start` to begin your RAG learning journey. The curriculum director will assess your current knowledge level and recommend a personalized learning path.
113152
114−- ✅ Use bd for ALL task tracking
115−- ✅ Always use `--json` flag for programmatic use
116−- ✅ Link discovered work with `discovered-from` dependencies
117−- ✅ Check `bd ready` before asking "what should I work on?"
118−- ❌ Do NOT create markdown TODO lists
119−- ❌ Do NOT use external issue trackers
120−- ❌ Do NOT duplicate tracking systems
153+Not sure where to go? Run `/triage` to get routed to the right skill based on your current needs.
121154
122−For more details, see README.md and docs/QUICKSTART.md.
155+## Content Freshness
123156
124−## Landing the Plane (Session Completion)
157+Academy materials are monitored for staleness via:
158+- **Session hook:** `check-freshness.sh` warns on startup if content files haven't been updated in 90+ days
159+- **On-demand audit:** Run `/audit-content` to scan for deprecated models, outdated libraries, and stale references
160+- **CI pipeline:** Monthly GitHub Actions workflow creates issues for stale content
161+- **Research director:** Extended with content currency auditing responsibilities
125162
126−**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
163+## Resource References
127164
128−**MANDATORY WORKFLOW:**
129−
130−1. **File issues for remaining work** - Create issues for anything that needs follow-up
131−2. **Run quality gates** (if code changed) - Tests, linters, builds
132−3. **Update issue status** - Close finished work, update in-progress items
133−4. **PUSH TO REMOTE** - This is MANDATORY:
134− ```bash
135− git pull --rebase
136− bd sync
137− git push
138− git status # MUST show "up to date with origin"
139− ```
140−5. **Clean up** - Clear stashes, prune remote branches
141−6. **Verify** - All changes committed AND pushed
142−7. **Hand off** - Provide context for next session
143−
144−**CRITICAL RULES:**
145−- Work is NOT complete until `git push` succeeds
146−- NEVER stop before pushing - that leaves work stranded locally
147−- NEVER say "ready to push when you are" - YOU must push
148−- If push fails, resolve and retry until it succeeds
149−
150−<!-- END BEADS INTEGRATION -->
165+- Curriculum details: `.claude/docs/curriculum/`
166+- Agent roster: `.claude/docs/reference/agent-roster.md`
167+- Coding standards: `.claude/docs/reference/coding-standards.md`
168+- Coordination rules: `.claude/docs/reference/coordination-rules.md`
151169
