CLAUDE.md — Maintainer Guide

Guidance for anyone (human or agent) editing this plugin. The user-facing document is README.md; this one is about how the thing is built and how to keep it coherent.

Architecture: three layers

  Layer 1   skills/orchestrator/SKILL.md
            Routing, startup sequence, settings, state, gates, delegation contract.
            Holds no domain knowledge and writes no deliverable.
                        │  delegates with an explicit prompt
                        ▼
  Layer 2   agents/*.md
            One agent per deliverable. Agents do not call each other; the
            orchestrator runs them and collects results.
                        │  loads, on demand, only what it needs
                        ▼
  Layer 3   references/*.md  +  templates/outputs/*
            Knowledge and shape. Inert: nothing here decides anything.
            execution/*.py sits beside this layer as optional tooling.

The separation is the point. Routing logic that leaks into an agent makes the agent unusable on its own. Teaching knowledge that leaks into the orchestrator gets loaded on every single request.

Which layer does a change belong in?

Hard authoring rules

1. SKILL.md stays under 500 lines. It loads on every invocation. Anything that is not routing, settings, state or gates belongs in a reference or a template. If it is growing, something has leaked down from Layer 3 or up from Layer 2.

2. Reference files stay under ~260 lines. They are loaded selectively and read in full when loaded. Past that, split by topic.

3. Nothing about a learner, school or course is hardcoded. No person's name, no institution, no program, no term dates, no credit rules, no grading scale. Registration rules, transfer requirements and academic calendars come from the learner's config or from research done at run time for that learner. A school-specific detail in an agent or template is a bug — it will be wrong for every other user. Examples use placeholders.

4. Settings are never decided by an agent. Languages (planning, content, glossary) and the four study_style axes come from workspace/config.json through the orchestrator's prompt. An agent that picks a language or a depth on its own is broken, even when it guesses right.

5. Kebab-case filenames throughout. teacher-agent.md, first-run-setup.md. Python files stay snake_case.py — a module name has to be importable.

6. Agent frontmatter. Every file in agents/ opens with:

---
name: agent-name          # MUST equal the filename stem: agents/agent-name.md
description: One sentence on what it owns, then one on when to use it. This is
             what the orchestrator matches against — write it for routing, not for a
             catalogue entry.
tools: Read, Write, Edit, Glob, Grep   # only what it needs
model: sonnet             # or opus for the planning agents
---

name mismatching the filename is the most common breakage: the orchestrator delegates by name and the agent silently does not exist.

7. Python scripts output JSON and degrade gracefully. Every script in execution/:

• has a module docstring covering purpose, dependencies and usage examples;
• exposes --help via argparse;
• prints JSON to stdout on success ({"ok": true, ...}) and on failure ({"ok": false, "error": {"code", "message", "fix"}}), exiting non-zero on failure;
• never emits a stack trace;
• names the install command or the manual fallback in the error, so the workflow continues;
• treats every non-standard-library dependency as optional: its absence degrades the output (Markdown instead of PDF), never blocks the task.

8. Everything in the repository is written in English. Source files, comments, docstrings, agent prompts, templates. The learner's languages govern deliverables at runtime, never the repo.

Adding a new agent

1. Check it earns a slot. Does it own a deliverable no existing agent owns? Overlapping agents make routing ambiguous, and ambiguous routing is worse than a missing agent.
2. Create agents/<agent-name>.md with name: <agent-name> matching the filename stem.
3. Write the description for routing: what it owns, then when to use it.
4. Grant the minimum tools. Only agents that run execution/ need Bash. Only agents that research need WebSearch / WebFetch.
5. Name the reference files it should load, specifically.
6. State its output contract: exact filenames, exact sections, which folder it writes in.
7. Register it in three places, or it is invisible:
   • the agents table in skills/orchestrator/SKILL.md (change planned to its phase)
   • the routing tables in skills/orchestrator/SKILL.md
   • the agents table in README.md
8. Add its files to the file-ownership table in SKILL.md. One writer per file, always.
9. If it can change a plan, it sits behind the PLAN CHANGE gate. No exceptions.

Source and rendered copies

Every study deliverable ships twice, and the distinction is load-bearing:

1. Only the source is ever read by an agent. Nothing may depend on a rendered copy.
2. Same agent, same run. The agent that writes the source renders the copy. Never split the pair across agents — that is how they drift.
3. Rendered copies originate nothing. A fact that exists only in the PDF is a gap in the source.
4. The converter is the only writer of a .pdf or .docx. No agent writes document code.
5. Never clobber the learner's annotations. The converter records each output's hash; a rendered copy whose hash changed was edited by hand, so the new version is written as -v2.
6. The converter is optional. Without its dependencies the Markdown stays as the deliverable and the agent passes on the install command.

Releasing

Every build that ships is published as a GitHub release, following semantic versioning.

1. Bump version in .claude-plugin/plugin.json — MAJOR.MINOR.PATCH, no v.
   • PATCH (0.1.0 → 0.1.1): a fix that changes no behaviour a user relies on.
   • MINOR (0.1.x → 0.2.0): a new agent, command, setting or deliverable.
   • MAJOR (0.x → 1.0.0, then 1.x → 2.0.0): 1.0.0 is the first release where the MVP (orchestrator + teacher-agent + quiz-agent) works end to end; after that, any change that breaks an existing workspace/config.json or folder layout.
2. Commit with a message that opens Release vX.Y.Z: <one-line summary>, followed by what changed — this body becomes the release notes.
3. Tag the commit vX.Y.Z — with the v, and equal to plugin.json. A tag and a manifest that disagree is a broken release.
4. Publish the GitHub release: title vX.Y.Z, notes from the commit body.

Maintenance

Before any release:

python3 -m py_compile execution/*.py          # scripts compile (once execution/ exists)
wc -l skills/orchestrator/SKILL.md            # under 500
wc -l references/*.md                         # each around 260 or less
grep -L '^name:' agents/*.md                  # every agent has frontmatter
python3 -m json.tool .claude-plugin/plugin.json > /dev/null

Then confirm each agent's name still equals its filename stem, and that any agent added or renamed appears in the orchestrator's tables and in README.md.

Grep for anything personal before every commit — a learner's name, a school, a course code:

git diff --cached | grep -niE '<your name>|<your school>|<your course codes>'