Flow & Dependency Maps

Visual maps for every load-bearing flow

Eight diagrams covering the state machine, dispatch cascade, agent harness, KB structure, review flow, gate topology, lifecycle states, and substrate boundaries.

Diagram 1 · Milestone state machine

M1 → M2 → M3 → M4 → Publish

Strategy / Outline

Artifacts produced

intake.mdcourse-outline.mdpedagogy.mdpreferences-*.mdnon-negotiables-*.md

explicit review action → readiness evidence recorded → next phase continues

Structure

Artifacts produced

units/unit-1/structure.mdunits/unit-2/structure.mdunits/unit-N/structure.md

explicit review action → readiness evidence recorded → next phase continues

Skeleton (Detailed Unit Content)

Artifacts produced

units/unit-N/modules/module-M.md

explicit review action → readiness evidence recorded → next phase continues

Substance (Lessons & Assignments)

Artifacts produced

units/.../lessons/lesson-L.mdunits/.../assignments/assignment-A.md

explicit review action → readiness evidence recorded → next phase continues

Publish

Artifacts produced

learning_content rows in Supabase

Diagram 2 · 4-state artifact lifecycle (D8)

draft → approved → finalized → published

State 1

draft

Just generated; teacher hasn't reviewed yet

State 2

approved

Teacher endorsed; triggers next sibling dispatch (D12)

State 3

finalized

Teacher closed; gate can fire; surface appears on left tree

State 4

published

Pushed via Formatter to learning_content; students see it

State transitions are git commits.The artifact's frontmatter status: field changes; the commit author tells you who made the transition (teacher@email vs agent:role).

Diagram 3 · Pipelined-sequential dispatch with APPROVED threshold (ADR 0008)

Sub-agent dispatches when prior reaches APPROVED

Teacher

(parent finalized)

System

Orchestrator dispatches sibling-1 sub-agent

State

sibling-1: dispatching

Teacher

(waiting)

System

sibling-1 generates

State

sibling-1: draft

Teacher

Reviews sibling-1

System

(idle, awaiting approve)

State

sibling-1: has_comments

Teacher

Approves sibling-1

System

Dispatches sibling-2 (reads sibling-1)

State

sibling-1: approved · sibling-2: dispatching

Teacher

Finalizes sibling-1

System

sibling-2 generates

State

sibling-1: finalized · sibling-2: draft

Teacher

Reviews sibling-2

System

(idle, awaiting approve)

State

sibling-2: has_comments

Teacher

Approves sibling-2

System

Dispatches sibling-3 (reads sibling-1 + sibling-2)

State

sibling-2: approved · sibling-3: dispatching

The accented rows are when overlap happens. Teacher is still on sibling-N while system generates sibling-(N+1). Zero idle time + low token risk.

Diagram 4 · Gates topology (8 milestone-crossing + 2 intra-milestone)

Every gate maps to one prompt

Gate	Fires at	Kind	Prompt
gate-outline-to-structure	M1 → M2	Crossing	gates/outline-to-structure.md
gate-planning-to-generation	M2 → M3	Crossing	gates/planning-to-generation.md
gate-between-modules	Within M3 + M4	Intra-milestone alignment	gates/between-modules.md
gate-unit-content-complete	Per-unit M3 close	Per-unit closure	gates/unit-closure-m3.md
gate-all-units-content-complete	M3 → M4	Crossing (cross-unit)	gates/all-units-closure-m3.md
gate-unit-lessons-complete	Per-unit M4 close	Per-unit closure	gates/unit-closure-m4.md
gate-all-units-lessons-complete	M4 → Publish	Crossing (cross-unit)	gates/all-units-closure-m4.md
gate-final-sign-off	Publish	Always-pauses (compliance)	gates/final-sign-off.md

Diagram 5 · Review findings and linear apply (ADR 0020 + 0023)

Review a change → apply it linearly → inspect readiness

Teacher opens units/unit-1/structure.md in left rail. Hits Review (not Edit).

Server action creates coordinator/review-proposals/units_unit-1_structure.md/001.md with base and proposed digests.

Teacher edits Big Idea inline. The proposed content stays in the review-proposal record.

Teacher hits Submit.

The current target digest is checked before the proposed content is applied.

Acceptance writes one linear snapshot. No judge, revision, or downstream repair action runs automatically.

Existing readiness reports and teacher review surface any downstream follow-up before Publish.

Diagram 6 · Prompts-as-agents harness (ADR 0005)

One Task primitive + N markdown prompts

Teacher (web UI)

Edit / Finalize / Comment / Approve / Chat / Publish

Server actions (Next.js)

Mount per-course git repo · Invoke Orchestrator inline · Enqueue sub-agent work · Commit + push

Inline

Async

Orchestrator (inline)

runAgentSession(socrates)

bounded tools · asks, dispatches, or pauses

Worker queue (async)

runAgentSession(delegated-task)

bounded tools · path-fenced reads and writes

Per-course git repo (Supabase Storage)

intake.md · course-outline.md · pedagogy.md

units/.../lessons/lesson-N.md

chat/ · comments/<path>/<id>.md

quality-reports/strategy · structure · substance

Publish (deterministic Formatter on finalized subtrees)

Supabase — ONLY published rows

learning_content (course / unit / module / lesson) · learning_content_versions

Diagram 7 · LLM Wiki at two scales (ADR 0006)

Course workspace is a wiki. KB is a wiki. Same pattern.

Wiki concept	Per-course workspace	Per-teacher KB
Raw sources	intake.md, fixtures, references	kb/sources/
Wiki core (mutable)	course-outline.md, units/, lessons/	kb/pages/
Schema file	CLAUDE.md (workspace) + curriculum-agents/prompts/*	kb/AGENTS.md
Index	workspace tree + topology manifest	kb/index.md
Log	Git history	Same — git history
Ingest	delegated course-generation task dispatches worker sessions	kb/librarian.md + kb/field-researcher.md
Query	Teacher review + milestone chat	Course sub-agents Task-invoke kb/context-researcher.md
Lint	Evaluator prompts at gates	kb/linter.md (cron + on-demand)
File-back	Resolved chat → comment thread back-reference	Resolved chat → new kb/pages/<topic>.md via chat-dock affordance

Diagram 8 · Edit vs Review duality (D22)

Two surfaces, one rule: cascade is opt-in

Edit (left-rail button)

Direct commit, no cascade

• For small tweaks on finalized artifacts
• Commits directly to main branch
• Status stays finalized
• Teacher takes responsibility for the change
• No LLM-judge cascade triggered
• Cheap; fast; minimal friction

Review (left-rail button)

Review proposal, cascade on accept

• For full reconsideration of finalized artifact
• Creates coordinator/review-proposals/<path>/<n>.md
• Status starts open; stale targets become rebase_needed
• Opens in review panel (PR-queue UX)
• Cascade fires on submit (LLM-judge for affected children)
• Acceptance = expected-digest write; teacher reviews the diff before applying

Cascade is opt-in by user intent, not auto-triggered by file save. Avoids surprising the teacher with cascade on a typo fix.

UI Layout Mockups

3-zone workspace · left sidebar 3-section · chat dock · review panel.

Companion

Full spec

All 44 decisions, build order, open questions.

Why

ADRs

Five load-bearing decisions with rationale + alternatives.

Back to design index

M1 → M2 → M3 → M4 → Publish

Strategy / Outline

Artifacts produced

intake.mdcourse-outline.mdpedagogy.mdpreferences-*.mdnon-negotiables-*.md

explicit review action → readiness evidence recorded → next phase continues

Structure

Artifacts produced

units/unit-1/structure.mdunits/unit-2/structure.mdunits/unit-N/structure.md

explicit review action → readiness evidence recorded → next phase continues

Skeleton (Detailed Unit Content)

Artifacts produced

units/unit-N/modules/module-M.md

explicit review action → readiness evidence recorded → next phase continues

Substance (Lessons & Assignments)

Artifacts produced

units/.../lessons/lesson-L.mdunits/.../assignments/assignment-A.md

explicit review action → readiness evidence recorded → next phase continues

Publish

Artifacts produced

learning_content rows in Supabase

draft → approved → finalized → published

State 1

draft

Just generated; teacher hasn't reviewed yet

State 2

approved

Teacher endorsed; triggers next sibling dispatch (D12)

State 3

finalized

Teacher closed; gate can fire; surface appears on left tree

State 4

published

Pushed via Formatter to learning_content; students see it

State transitions are git commits.The artifact's frontmatter status: field changes; the commit author tells you who made the transition (teacher@email vs agent:role).

Sub-agent dispatches when prior reaches APPROVED

Teacher

(parent finalized)

System

Orchestrator dispatches sibling-1 sub-agent

State

sibling-1: dispatching

Teacher

(waiting)

System

sibling-1 generates

State

sibling-1: draft

Teacher

Reviews sibling-1

System

(idle, awaiting approve)

State

sibling-1: has_comments

Teacher

Approves sibling-1

System

Dispatches sibling-2 (reads sibling-1)

State

sibling-1: approved · sibling-2: dispatching

Teacher

Finalizes sibling-1

System

sibling-2 generates

State

sibling-1: finalized · sibling-2: draft

Teacher

Reviews sibling-2

System

(idle, awaiting approve)

State

sibling-2: has_comments

Teacher

Approves sibling-2

System

Dispatches sibling-3 (reads sibling-1 + sibling-2)

State

sibling-2: approved · sibling-3: dispatching

The accented rows are when overlap happens. Teacher is still on sibling-N while system generates sibling-(N+1). Zero idle time + low token risk.

Every gate maps to one prompt

Gate	Fires at	Kind	Prompt
gate-outline-to-structure	M1 → M2	Crossing	gates/outline-to-structure.md
gate-planning-to-generation	M2 → M3	Crossing	gates/planning-to-generation.md
gate-between-modules	Within M3 + M4	Intra-milestone alignment	gates/between-modules.md
gate-unit-content-complete	Per-unit M3 close	Per-unit closure	gates/unit-closure-m3.md
gate-all-units-content-complete	M3 → M4	Crossing (cross-unit)	gates/all-units-closure-m3.md
gate-unit-lessons-complete	Per-unit M4 close	Per-unit closure	gates/unit-closure-m4.md
gate-all-units-lessons-complete	M4 → Publish	Crossing (cross-unit)	gates/all-units-closure-m4.md
gate-final-sign-off	Publish	Always-pauses (compliance)	gates/final-sign-off.md

Review a change → apply it linearly → inspect readiness

Teacher opens units/unit-1/structure.md in left rail. Hits Review (not Edit).

Server action creates coordinator/review-proposals/units_unit-1_structure.md/001.md with base and proposed digests.

Teacher edits Big Idea inline. The proposed content stays in the review-proposal record.

Teacher hits Submit.

The current target digest is checked before the proposed content is applied.

Acceptance writes one linear snapshot. No judge, revision, or downstream repair action runs automatically.

Existing readiness reports and teacher review surface any downstream follow-up before Publish.

One Task primitive + N markdown prompts

Teacher (web UI)

Edit / Finalize / Comment / Approve / Chat / Publish

Server actions (Next.js)

Mount per-course git repo · Invoke Orchestrator inline · Enqueue sub-agent work · Commit + push

Inline

Async

Orchestrator (inline)

runAgentSession(socrates)

bounded tools · asks, dispatches, or pauses

Worker queue (async)

runAgentSession(delegated-task)

bounded tools · path-fenced reads and writes

Per-course git repo (Supabase Storage)

intake.md · course-outline.md · pedagogy.md

units/.../lessons/lesson-N.md

chat/ · comments/<path>/<id>.md

quality-reports/strategy · structure · substance

Publish (deterministic Formatter on finalized subtrees)

Supabase — ONLY published rows

learning_content (course / unit / module / lesson) · learning_content_versions

Course workspace is a wiki. KB is a wiki. Same pattern.

Wiki concept	Per-course workspace	Per-teacher KB
Raw sources	intake.md, fixtures, references	kb/sources/
Wiki core (mutable)	course-outline.md, units/, lessons/	kb/pages/
Schema file	CLAUDE.md (workspace) + curriculum-agents/prompts/*	kb/AGENTS.md
Index	workspace tree + topology manifest	kb/index.md
Log	Git history	Same — git history
Ingest	delegated course-generation task dispatches worker sessions	kb/librarian.md + kb/field-researcher.md
Query	Teacher review + milestone chat	Course sub-agents Task-invoke kb/context-researcher.md
Lint	Evaluator prompts at gates	kb/linter.md (cron + on-demand)
File-back	Resolved chat → comment thread back-reference	Resolved chat → new kb/pages/<topic>.md via chat-dock affordance

Two surfaces, one rule: cascade is opt-in

Edit (left-rail button)

Direct commit, no cascade

• For small tweaks on finalized artifacts
• Commits directly to main branch
• Status stays finalized
• Teacher takes responsibility for the change
• No LLM-judge cascade triggered
• Cheap; fast; minimal friction

Review (left-rail button)

Review proposal, cascade on accept

• For full reconsideration of finalized artifact
• Creates coordinator/review-proposals/<path>/<n>.md
• Status starts open; stale targets become rebase_needed
• Opens in review panel (PR-queue UX)
• Cascade fires on submit (LLM-judge for affected children)
• Acceptance = expected-digest write; teacher reviews the diff before applying

Cascade is opt-in by user intent, not auto-triggered by file save. Avoids surprising the teacher with cascade on a typo fix.