| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 16 | 14 | 0% |
| Commands | 0 | 0 | 5 | 0% |
| Section tags | 1 | 2 | 3 | 17% |
What each file covers
Sections
0 shared · 16 only in A · 14 only in B- − 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
- + 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)
Commands
0 shared · 0 only in A · 5 only in B- + git pull --rebase
- + git push
- + git status
- + task
- + git pull
Section tags
1 shared · 2 only in A · 3 only in B- − setup
- − architecture
- + code-style
- + types
- + do-not
- agent-behaviour
Line diff
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
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
@@ −1 +1 @@
1−# RAG Learning Academy — Multi-Agent Learning Architecture
1+# Agent Instructions
22
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.
3+This project uses **bd** (beads) for issue tracking. Run `bd onboard` to get started.
44
5−## Philosophy
5+## Quick Reference
66
7−> "Understand → Build → Evaluate → Iterate"
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+```
814
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.
15+## Non-Interactive Shell Commands
1016
11−## Voice & Tone
17+**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
1218
13−All agents and skills follow this voice. The academy should feel like learning from a sharp, experienced friend — not reading a textbook.
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.
1420
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.
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
2527
26−For tone examples, see `.claude/docs/reference/voice-examples.md`.
28+# For recursive operations
29+rm -rf directory # NOT: rm -r directory
30+cp -rf source dest # NOT: cp -r source dest
31+```
2732
28−## Collaboration Framework
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
2938
30−All agents follow this interaction model:
39+<!-- BEGIN BEADS INTEGRATION -->
40+## Issue Tracking with bd (beads)
3141
32−> "Question → Explanation → Options → Hands-On → Review"
42+**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
3343
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
44+### Why bd?
3945
40−### Agent Suggestions
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
4150
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:
51+### Quick Start
4352
44−> "For a deeper dive, the **[agent-name]** has specific guidance on [topic] — want me to bring it in?"
53+**Check for ready work:**
4554
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
55+```bash
56+bd ready --json
57+```
5058
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)
59+**Create new issues:**
5660
57−This keeps the UX lightweight — no extra token cost unless the learner opts in.
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+```
5865
59−## Agent Hierarchy
66+**Claim and update:**
6067
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 |
68+```bash
69+bd update <id> --claim --json
70+bd update bd-42 --priority 1 --json
71+```
6772
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 |
73+**Complete work:**
7674
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 |
75+```bash
76+bd close bd-42 --reason "Completed" --json
77+```
9278
93−## Curriculum Modules
79+### Issue Types
9480
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 |
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)
10686
107−## Learning Skills (Slash Commands)
87+### Priorities
10888
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 |
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)
13394
134−## Tech Stack (Default)
95+### Workflow for AI Agents
13596
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
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"`
143103
144−## Directory & Token Reference
104+### Auto-Sync
145105
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)
106+bd automatically syncs with git:
148107
149−## Getting Started
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!
150111
151−Run `/start` to begin your RAG learning journey. The curriculum director will assess your current knowledge level and recommend a personalized learning path.
112+### Important Rules
152113
153−Not sure where to go? Run `/triage` to get routed to the right skill based on your current needs.
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
154121
155−## Content Freshness
122+For more details, see README.md and docs/QUICKSTART.md.
156123
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
124+## Landing the Plane (Session Completion)
162125
163−## Resource References
126+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
164127
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`
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 -->
169151
