Multi-topic study orchestrator. Manages multiple knowledge bases (DevOps, project codebases, certifications) each with independent progress tracking. Use when the user says "/study-buddy", "study-buddy", "study buddy", "switch topic", "generate kb", "generate knowledge base", "enrich", "enrich kb", "enrich knowledge base", "add coverage for", "fill gaps", "find missing topics", "resume path", "show path", "path status", "list paths", "my paths", "generate guides", "expand guide", "deeper guide", "guide for", "sandbox", "sandbox challenge", or references a specific study topic by name. Delegates to the study engine skill for actual learning interactions.
Manages multiple study topics, each with its own knowledge base and progress. Delegates to the study engine skill (/study) for actual learning interactions (LEARN, QUIZ, SCENARIO, PROJECT, MASTERY CHALLENGE, STATUS, PATH).
/Users/sethallen/DSP/SEIJIV2/_meta/study-buddy/
Global config: {data_root}/config.yaml
A topic is any subdirectory of the data root that contains a study.yaml file. No registry to maintain — adding a topic is creating a directory with study.yaml and knowledge-base.yaml.
To discover topics:
.git, node_modules, hidden dirs)study.yaml existsdevopsarchon/study-buddy (no arguments) — List Topicsstudy.yaml to get name and descriptionAvailable Topics:
devops DevOps & Platform Engineering 42/209 engaged
archon Archon Framework 0/87 engaged
Use /study-buddy [topic] to start studying.
/study-buddy [topic] — Activate Topicstudy.yaml{skill_source}/SKILL.mdpython3 {skill_source}/scripts/kb-stats.py {kb_path}Path Override — CRITICAL: When executing the study engine's behavior for the active topic, replace ALL hardcoded paths from the study engine's SKILL.md with the resolved paths below. The study engine's SKILL.md references its own default KB; you MUST use the topic's KB instead.
/study-buddy generate [source] — Generate New TopicSee the Generation section below.
/study-buddy enrich [topic] — Enrich Existing KBSee the Enrichment section below.
Given a topic at {data_root}/{slug}/:
| Resource | Path |
|---|---|
| Knowledge base | {data_root}/{slug}/knowledge-base.yaml |
| study.yaml | {data_root}/{slug}/study.yaml |
| Skill source | study.yaml → skill.source, falling back to config.yaml → defaults.skill_source |
| Stats script | python3 {skill_source}/scripts/kb-stats.py {kb_path} |
| DAG script | python3 {skill_source}/scripts/kb-dag.py --kb {kb_path} |
| Skill SKILL.md | {skill_source}/SKILL.md |
| Skill references | {skill_source}/references/ |
| Saved paths | {data_root}/{slug}/paths/*.yaml |
| Topic guides | {data_root}/{slug}/docs/ |
| Sandbox challenges | {data_root}/{slug}/sandbox/ |
When operating in study mode for an active topic, use these paths instead of any hardcoded paths in the study engine's SKILL.md:
{data_root}/{slug}/knowledge-base.yaml (replaces the study engine's default KB path)python3 {skill_source}/scripts/kb-stats.py {data_root}/{slug}/knowledge-base.yamlpython3 {skill_source}/scripts/kb-dag.py --kb {data_root}/{slug}/knowledge-base.yaml{skill_source}/references/ (unchanged — these are engine docs, not topic-specific){data_root}/{slug}/knowledge-base.yaml{skill_source}/references/yaml-editing-patterns.md apply, but the file path is the topic's KBsource_context is a relative path ending in .md, resolve to {data_root}/{slug}/{source_context}. The study engine should Read this resolved path to ground its teaching.{data_root}/{slug}/sandbox/. The study engine generates sandbox files here, using the topic slug as the subdirectory name. The slug rule is the same as for guide filenames (defined in references/guide-generation.md).Once a topic is activated, all study interactions follow the study engine's SKILL.md exactly, with the path overrides above. The user interacts normally — "teach me X", "quiz me on Y", "study status" — and the orchestrator transparently routes to the correct KB.
Exception — ad-hoc prerequisites: When an active path exists and LEARN mode flags a prerequisite gap that the user chooses to address, the orchestrator performs additional steps (guide generation, path update) before delegating to the study engine. See "Ad-Hoc Prerequisite Handling During Path Execution" below.
The user can switch topics at any time with /study-buddy [other-topic].
Trigger: During LEARN mode with an active path, the study engine flags a prerequisite gap (interaction-modes.md step 3) and the user chooses to learn the prerequisite first.
Flow:
topics list so it comes before the topic that needs it. Use mode: LEARN and target: exposed (minimum useful prerequisite level). Update summary.topics_covered count (+1). Use the Edit tool with the session header + first existing topic as the old_string anchor.references/guide-generation.md. Check if {data_root}/{slug}/docs/{topic-slug}.md exists.
references/guide-generation.md instructions (web research, full template, all sections substantive). If the topic's current source_context is a non-path string, capture it in the guide's Further Reading section.source_context in the KB to point to the guide (e.g., "docs/x-509-certificate.md"). Use the full topic block as old_string per yaml-editing-patterns.md Pattern 1 / Safety Rule 3.resume path step 7 — ask if the user wants the guide expanded with a more comprehensive deep-dive before proceeding. This applies to all guides, including freshly generated ones.source_context points to .md file). Proceed with LEARN mode step 4 using the guide-first flow (present path → summary → verification questions).Recursive prerequisites: If the pulled-forward prerequisite itself has prerequisites at not_started, the LEARN flow for that topic will flag them (step 3), and this entire ad-hoc handling flow triggers again. Each level is handled one topic at a time.
Path YAML edit pattern: To prepend a topic to a session, use the Edit tool:
old_string:
- number: N
theme: "Session Theme"
topics:
- name: "First Existing Topic"
mode: LEARN
target: exposed
new_string:
- number: N
theme: "Session Theme"
topics:
- name: "New Prerequisite Topic"
mode: LEARN
target: exposed
- name: "First Existing Topic"
mode: LEARN
target: exposed
Include enough of the first existing topic entry (all 3 fields) to guarantee uniqueness.
A path is a YAML file in {topic_dir}/paths/ that captures a sequenced learning plan.
Any .yaml file in {data_root}/{slug}/paths/ is a path. The filename (without extension) is the path slug.
show paths / list paths — List Available Paths{data_root}/{active_topic}/paths/*.yamlname, status, and summaryresume path [name] — Resume a Pathreferences/path-yaml-schema.md){data_root}/{slug}/docs/{topic-slug}.md existsreferences/guide-generation.md for instructions)source_context in the KB for each newly generated guidereferences/guide-generation.md, then proceedpath status — Detailed Path ProgressComprehensive guide documents are generated per-session during path resume. The orchestrator handles all guide generation (web research, file writes, KB updates) — the study engine only reads finished guides.
Guides live in {data_root}/{slug}/docs/. The filename is derived from the
topic name using the slug conversion rule in references/guide-generation.md.
A guide exists if the computed file path resolves to an actual file.
resume path: missing guides for the current session's
topics are generated before teaching begins (step 5 of resume path)resume path
step 5, including web research and KB source_context updateAfter writing a guide file, update the topic's source_context in the KB
to point to the guide. Use Pattern 1 from {skill_source}/references/yaml-editing-patterns.md:
include the full topic block from - name: through source_context: (and
resources: if present) as the old_string, changing only the source_context value.
For topics where source_context is null, match the literal string null
(Safety Rule 5 from yaml-editing-patterns.md).
For topics where source_context has an existing non-path value (e.g.,
"kubernetes-internals-guide, Part III Chapter 3"), the old value is captured
in the guide's Further Reading section before being replaced.
/study-buddy generate [source]Creates a new topic from a project codebase, documentation, or URL.
| Source | Syntax | Handling |
|---|---|---|
| Local project | /study-buddy generate /path/to/project | Read files directly via Glob/Grep/Read |
| GitHub repo | /study-buddy generate https://github.com/user/repo | Clone via git clone --depth 1 to temp dir, then analyze as local |
| Documentation | /study-buddy generate /path/to/docs --type docs | Documentation-only analysis (no source code) |
Read references/kb-generation-guide.md for the detailed methodology, then execute:
Step 1: Accept input and determine topic slug
/path/to/archon, "repo-name" from GitHub URL){data_root}/{slug}/ doesn't already existStep 2: Analyze the source
references/kb-generation-guide.md for language-specific analysis instructionsStep 3: Generate the knowledge base
not_started), source_context, resources (optional — omit if no resources exist yet)Step 4: Generate study.yaml