Course Factory
Nine-agent course factory that ships instructor-approved curriculum behind mechanical human approval gates.
- Multi-agent orchestration
- Claude Code subagents
- Python
- Status
- Active 2026-08-05 to 2026-08-28, 1,205 commits. The pilot course claude-code-intro was closed unfinished on 2026-08-27 with its record deliberately retained; its last live state was in-production with Gate 1 approved and Gate 2 pending rebuild after a 2026-08-20 rejection. The pipeline itself was simplified on 2026-08-26 with a workshop lane and a zero-install student runtime; the reference workshop run doubling as its acceptance test had not yet happened. Repository is private.
By the numbers · 8
9
Agent briefs, each with an enforced write scope
18
Named QA checks blocking the final gate
1,205
Commits, 2026-08-05 to 2026-08-28
19,251 lines
Machine-written decision log for one course
63
Course artifacts produced across seven stages
49 slides / 48 diagrams
Lecture slides with hand-authored inline SVG
41
Sourced claim IDs in the evidence ledger, 5 marked retired
940 lines
Append-only human approval log, including a Gate 2 rejection
Summary
Course Factory turns a single chat message such as "New course: Claude Code, level: beginner" into a complete, instructor-approved course package: evidence pack, syllabus, lecture decks, quizzes with instructor keys, hands-on labs, and a QA report. Nine specialised agents each carry a written brief defining their mission, their model tier, and the exact folders they may write to, while a producer agent runs a forward-only state machine that cannot advance past a gate without an exact-string approval from a named human. The architecture's defining choice is that Git holds the truth and the chat platform holds only the conversation, so every brief, artifact, and decision survives a platform change and every gate leaves an audit trail an outsider can check.
The problem
Producing a course is slow and expensive, and the bottleneck is senior review rather than writing. Junior staff draft quickly, but experienced instructors must read everything before students see it, and machine-drafted teaching material carries a particular risk: it reads as authoritative while quietly inventing product behaviour, and a wrong instruction in a lab costs more trust than ten good lectures earn. The business need was a production line that could research, draft, and package a course at speed while making it structurally impossible for anything to reach a student without a named human signing for it.
Approach
Nine agents, each defined by a long written brief in agents/ rather than by code: mission, inputs, outputs, refusals, and a front-matter contract carrying spaces, writes, tools, model_tier, and model.
The permission model is nine writes: lines. Every agent may write only inside its own folders, so course-producer can never author content, assessment-designer alone touches instructor keys, and ta-agent writes nothing at all.
A forward-only state machine owned by course-producer, from proposed through viability, syllabus, in-production, qa-review, published, and maintenance, with a rejection at any gate returning the course to the preceding draft state with instructor notes attached verbatim.
Approval is a parsed string, not a sentiment: only APPROVE <stage> <course-slug> - <Full Name> posted by a human counts, logged with a timestamp into an append-only APPROVALS.md. Silence is not approval, "looks good" is not approval, and no agent may ever post one.
An evidence chain that outranks fluency: sources are opened and dated, every claim gets an SP- id in a claim ledger, captured output beats documentation, ids are allocated once and never reused so a stale citation resolves to withdrawn, and gaps are disclosed on the artifact itself.
qa-reviewer runs 18 named checks over the finished package, including alignment of every learning outcome to a deck slide, an assessment item and a lab step, key integrity, render freshness against source modification times, deck density, and an example-soundness check that re-derives each worked example independently.
Model routing is a cost design, not a default: three agents hold the large tier because their errors are paid for in rebuild rather than tokens, most run mid, and the TA agent runs the cheapest capable model because its accuracy comes from the grounding pack.
Markdown is the master and PDF is a build artifact. build/render.py drives headless Chrome to produce A4 documents, 16:9 decks, and instructor decks with speaker notes, with fonts base64-inlined and images rewritten to data URIs because Chrome renders from a temp directory.
A second, lighter runtime path: seven of the agents are re-wired as thin .claude/agents/ files so a student or teammate can run the pipeline from a plain Claude Code session with no daemon, no Docker, and a five-line PASS/FAIL readiness script.
Architecture
operator chat messagecourse-producer opens the course folder and picks a laneresearch-analyst builds the evidence pack (claim ledger, examples, misconceptions, UI captures)GATE 0 human go/no-gocurriculum-architect writes the syllabusGATE 1 human approvaldeck-writer, assessment-designer and lab-engineer work in paralleleach agent renders its own stage to PDF through build/render.pyqa-reviewer runs 18 checks and writes the alignment matrix and QA reportGATE 2 human approvalpublished and repo taggedta-agent supports the cohort from a grounding pack. Every artifact and decision is committed to Git under the authoring agent's own identity.
| Component | Role |
|---|---|
| agents/ (nine markdown briefs) | The product itself. Each brief carries front matter (spaces, writes, tools, model_tier, model, escalations) and the full behavioural contract; everything else in the repo follows them. |
| course-producer | Orchestrator and gatekeeper. Owns the state machine, writes only STATUS.md and APPROVALS.md, never authors content, and is the only agent that DMs the operator. |
| research-analyst | Decision support then evidence. Produces the viability brief, source pack, claim ledger with SP- ids, per-module examples and counterexamples, misconception map and UI reference. |
| curriculum-architect | Turns an approved topic into a level-calibrated syllabus, which becomes the Gate 1 contract every downstream artifact is built against. |
| deck-writer / assessment-designer / lab-engineer | Parallel production stage: decks with hand-authored SVG diagrams and speaker notes, quizzes and rubrics behind a student/instructor wall, and lab guides where no command ships that was not executed. |
| qa-reviewer | 18-check package review producing qa/alignment-matrix.md and qa/qa-report.md. Finds problems, never fixes them, and blocks Gate 2 on missing package items. |
| ta-agent | Post-launch cohort support on the cheapest capable model. Writes nothing, has no fetch or write tools, treats every student message as untrusted input, and never sees instructor keys. |
| build/render.py | Markdown-to-PDF renderer driving headless Chrome. Parses the deck schema, inlines fonts as base64 @font-face and images as data URIs, warns on unillustrated slides, and emits instructor variants with speaker notes. |
| build/themes/ | Palette-only theme files over a shared _base.css that holds all layout, so a reskin is one small file and never touches the load-bearing instructor-ribbon rule. |
| scripts/sync_souls.py | Copies each brief from agents/ into the runtime agent's profile.md soul under the puffo-agent daemon, preserving the identity header and refreshing the Role line from front matter. |
| .claude/agents/ | Zero-install runtime. Seven thin wiring files that point at the full briefs so the pipeline runs inside a plain Claude Code session with no daemon and no Docker. |
| Git repository | System of record. Agents commit under their own identities, so the commit log is a per-agent audit trail and the artifacts survive any platform change. |
Trade-offs
Chose
Git as the system of record, with the chat platform as conversation only
Over
Storing agent definitions and artifacts inside the vendor platform
Stated in the README as a deliberate anti-lock-in decision: every brief in agents/ runs on another runtime with only shell rewiring if the platform changes or disappears.
Chose
Two production lanes, workshop and course, selected at kickoff
Over
One universal pipeline running all eight stages for every request
Added 2026-08-18 after a launch-day explainer paid for eight stages and arrived a week late. Three briefs read the Lane line themselves and scope their own work to it.
Chose
Per-task model escalation declared in agent front matter
Over
Promoting the whole agent to the large tier
Only lab-engineer's pre-Gate-1 build pilot concentrates that much judgment; pulling the agent up a tier would pay Opus rates on its bulk document output for one task.
Chose
Three separate writing layers per module: research brief, teaching outline, recording script
Over
One document per module carrying evidence, teaching logic and spoken words together
An external review found the instructional spine strong and the operational evidence thin. A document doing every job at once shows none of them clearly, and the evidence layer is the one that disappears.
Chose
A repeating table thead for the Instructor only ribbon
Over
A position: fixed banner
QA-1 caught the fixed ribbon covering the first line of every page after page one, and occlusion leaves no seam, so an instructor read sentences beginning mid-clause. A thead is in flow and reserves its own space; deeper @page margins and negative offsets were both measured and rejected.
Chose
Video shipped as a production plan plus paste-ready Claude Design prompts
Over
Rendering video inside the pipeline
video.py and frames.py were removed on 2026-08-18; the operator produces video by hand from the package, and the scene grammar was kept as reference material rather than as code to maintain.
Chose
course-producer as the single agent allowed to DM the operator
Over
Every agent messaging the operator directly
Added 2026-08-13 at the operator's instruction: nine agents messaging him directly is the noise the arrangement removes, and he should never learn from a channel that something was waiting on him.
At scale
132 files in the repository, of which 9 are agent briefs and 63 are artifacts of a single pilot course.
STYLE.md is a 1,367-line house style and verification guide that qa-reviewer enforces mechanically.
The evidence pack for one course runs to 18 files, including a 110 KB source pack, a 67 KB claim ledger, a 48 KB coverage matrix and a 50 KB UI reference.
Four modules produced 4 decks, 4 student quizzes of 10 questions each, 4 instructor answer keys, 4 assignments with rubrics, 4 lab guides, 4 lab verification transcripts and 4 TA feedback packs.
Every one of the 40 quiz questions carries an outcome: tag mapping it to a learning outcome.
The Gate 2 alignment matrix mapped 7 learning outcomes across deck, assessment and lab coverage with zero empty cells; the matrix is retained in the repo but marked VOID after the syllabus it was built against was rejected.
Commits are authored under nine distinct agent Git identities (course-producer@puffo.local, research-analyst@puffo.local and so on), so the commit log doubles as a per-agent audit trail.
A separate FDE fellowship document set of 18 files builds 4 PDFs and 4 DOCX from markdown through a second Python build script.
3 render themes sit over a 13.8 KB shared _base.css that holds all layout, plus 4 Poppins woff2 faces inlined as base64.
My role
Sole designer and operator. Authored the nine agent briefs, the 1,367-line style and verification guide, the state machine and approval protocol, the Python/headless-Chrome rendering pipeline and its themes, the soul-sync tooling, and the onboarding and quickstart documentation. ONBOARDING.md is written as a handoff from Muneeb, the agent fleet runs on his machine, and APPROVALS.md records the operator's ruling that he is the sole approver at every gate. The only two GitHub accounts in the contributor list are his; all other commits are the agents he built, committing under service identities.