From 116f42543197067342bb3ed773253f3be14c0def Mon Sep 17 00:00:00 2001 From: Daniel Bejarano Date: Mon, 1 Jun 2026 20:48:59 -0600 Subject: [PATCH 1/5] DOJ-4798: add workbook-generate command + skill + interactive base template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Voice-neutral IDTK surface that turns a course's text classes into one standalone, accessible, interactive HTML workbook (Rise/Typeform-style), held to the editorial quality bar of interactive-HTML explainers. - commands/workbook-generate.md — spec resolution (sibling/remote/graceful- degrade), per-course discovery + ordering, content->component mapping, overlay invocation, ${CLAUDE_PLUGIN_ROOT} defensive note - skills/workbook-generate/SKILL.md — IDT-owned component catalog + mapping rules + accessibility contract + consumer-spec consumption rules - assets/templates/workbook/workbook-base.html — self-contained template: design-system CSS layer (type/spacing/radius/shadow scales, 1.5px borders, panels+elevation, mono eyebrows, editorial headings), vanilla-JS engine, full component kit (progressive disclosure, inline SVG, annotated code, quiz/free-text, comparison table, term->glossary) State is in-memory only (persistence deferred to V2). No CDN runtime deps. The consumer's instruction-bundle-spec.yaml themes + optionally tunes the catalog; the library itself stays in IDT base, voice-neutral. CI lint green. Created by Claude Code on behalf of @daniel Co-Authored-By: Claude Opus 4.8 (1M context) --- assets/templates/workbook/workbook-base.html | 574 +++++++++++++++++++ commands/workbook-generate.md | 172 ++++++ skills/workbook-generate/SKILL.md | 222 +++++++ 3 files changed, 968 insertions(+) create mode 100644 assets/templates/workbook/workbook-base.html create mode 100644 commands/workbook-generate.md create mode 100644 skills/workbook-generate/SKILL.md diff --git a/assets/templates/workbook/workbook-base.html b/assets/templates/workbook/workbook-base.html new file mode 100644 index 0000000..46208a4 --- /dev/null +++ b/assets/templates/workbook/workbook-base.html @@ -0,0 +1,574 @@ + + + + + + +{{course.title}} — Workbook + + + + + + + + +
+
+
+ + + + +
+
+ + + + +
+
+
Interactive Workbook
+

{{course.title}}

+

{{course.promise}}

+
+
+ + +
+
+
{{module.title}}
+
+

{{step.title}}

+

{{step.body}} A key term like the ring can be linked to the glossary below.

+ + +
{{key word}} {{statement}}
+ + +
+ + +
+ + +
+
+ + +
+
{{panel A}}
+ +
+ + +
+ + 
{{code}}
+
    +
  • {{annotation}}
    • +
+
+ + +
+ + + + + + + + + {{step A}} + + + + + {{step B}} + + +
{{caption}}
+
+ + + + + + + +
{{dimension}}{{option A}}{{option B}}
{{row}}{{weak}}{{strong}}
+ + +
+

{{question}}

+ + + +
+ + +
+ + +
+ + +
+ + +
+ + +
+
{{term}}
+
{{definition}}
+
+
+ + +
+
+ +

{{recap heading}}

+

{{recap body}}

+
+
+ + +
+ + +
+
+
+ + + + diff --git a/commands/workbook-generate.md b/commands/workbook-generate.md new file mode 100644 index 0000000..fc7c49f --- /dev/null +++ b/commands/workbook-generate.md @@ -0,0 +1,172 @@ +--- +description: Generate one standalone interactive HTML workbook for a whole course from its text classes +argument-hint: "[course-slug] [--scope course|module] [--module module-slug]" +--- + +# Workbook Generate + +You are generating a **standalone interactive workbook** — a single, +self-contained HTML file that renders a course's **text classes** (`text-*.md`) +as an interactive explainer the learner scrolls or steps through +(Rise/Typeform-style continuous flow). + +This is the student-facing sibling of `course-visualize` (instructor analytics +view). It is distinct from `slides-generate`, which turns a **video brief** into +a deck. Workbooks consume the **reading classes**, not video briefs. + +Read the design system first: +`${CLAUDE_PLUGIN_ROOT}/skills/workbook-generate/SKILL.md` — it defines the +component kit, the content-shape -> component mapping rules, the accessibility +contract, and the spec-consumption + graceful-degrade rules. + +**Arguments format**: `{course-slug} [--scope course|module] [--module {module-slug}]` +- `course-slug`: the course to render. Resolved against the consumer's content + layout (e.g. `content/courses/{course-slug}/` in a dojo-academy-shaped repo). +- `--scope`: `course` (default) emits one workbook over all modules; `module` + emits one workbook for a single module (requires `--module`). +- `--module`: the module slug, when `--scope module`. + +## Phase 1 — Resolve the consumer spec (brand + structural vocabulary) + +The workbook's palette, typography, voice, scroll behaviour, step patterns, and +component catalog come from the consumer's `instruction-bundle-spec.yaml`. +Resolve it in this order: + +1. **Sibling-repo path first**: `../{consumer}/instruction-bundle-spec.yaml` + (e.g. `../dojo-academy/instruction-bundle-spec.yaml`). +2. **Remote raw fallback** (5s timeout): the consumer's documented raw URL + (e.g. `https://raw.githubusercontent.com/DojoCodingLabs/dojo-academy/main/instruction-bundle-spec.yaml`). +3. **Graceful degrade**: if neither resolves, continue with **neutral defaults** + (system-ui typography, a single monochrome accent, a generic stepped layout) + and emit a **visible WARNING** — both to the user and as an HTML comment at + the top of the generated file. Never crash, and never silently behave as if + the spec had requested neutral defaults. + +**Validate before generating** (fail fast with a path-pointing error) that the +resolved spec has: `design.palette.accent`, `design.typography.family.body`, +and `workbooks.step_patterns`. Read: +- `design` -> palette / typography / voice / spacing / components. +- `workbooks.scroll_behavior`, `workbooks.animation`, `workbooks.step_patterns`. +- `workbooks.components` (OPTIONAL) -> **consumer overrides on top of IDT's + built-in component library**. The canonical catalog ships in IDT base (this + command's skill + the base template) and is voice-neutral — the consumer spec + is NOT the source of the library. When present, this key lets a consumer + enable/disable components, set options, or opt into stretch-tier components. + **When absent, use IDT's full built-in catalog with sensible defaults** — the + workbook is fully rich, not plainer. The library lives in IDT; only brand + theming and thin preferences live in the consumer spec. + +## Phase 2 — Discover & order the course content + +1. Locate the course root (e.g. `content/courses/{course-slug}/`). +2. Enumerate modules (e.g. `module-NN-*/`) and order them by their numeric + prefix. +3. Within each module's `classes/` directory, collect every **`text-*.md`** + reading. Order them by the `order` frontmatter field (fall back to the + filename's numeric prefix). +4. For `--scope module`, restrict to the named module only. +5. Note sibling artifacts for cross-reference (do NOT embed them): + - `quiz-*.md` -> fold in as module **checkpoints** (see Phase 3). + - `video-*.md`, `slides-*.html`, `challenge-*.md` -> may be **referenced** + with a symbolic ref / link, never embedded (video embedding is out of + scope). +6. Read each reading's frontmatter (`title`, `order`, `duration_min`, `module`, + `course`, `tags`) and body (H1 -> H2 -> H3, lists, tables, code, prose). + +## Phase 3 — Map content to components + +Apply the **content-shape -> component mapping** from the skill. Summary: + +- Course -> module **chapters** + a **table of contents** + course **progress**. +- Each reading -> a run of steps in its module chapter; each `H2` -> a **step**. +- Tables -> **comparison diagram** / **tabs** / **chart** (by intent). +- Ordered process lists -> **flow diagram** / stepper. +- Fenced code -> **annotated code block**. +- Load-bearing sentences -> **statement / callout**. +- Optional depth -> **accordion**; parallel alternatives -> **tabs**. +- End of each major section -> an optional auto-generated **multiple-choice** + check drawn from the reading; `quiz-*.md` -> module **checkpoint** questions. +- Course intro -> **hero**; course end -> **recap** + **completion event**. + +Only use a component the resolved spec's `workbooks.components` enables (or the +neutral defaults when that key is absent). Interactivity must earn its place — +prefer one well-chosen block per concept over decorative ones. + +## Phase 4 — Generate the standalone HTML + +1. Start from the base template: + `${CLAUDE_PLUGIN_ROOT}/assets/templates/workbook/workbook-base.html`. It + ships the full CSS runtime, the vanilla-JS flow/progress/quiz/disclosure + engine, and example markup for every component. +2. Inline the resolved `design` palette/typography as the template's CSS custom + properties (`:root` variables). Under graceful-degrade, keep the neutral + defaults already in the template. +3. Replace the content region between the WORKBOOK CONTENT markers with the + composed module chapters, steps, and components from Phase 3. +4. Honour `workbooks.scroll_behavior` (scroll-snap vs stepped) and + `workbooks.animation` (enter transition + `prefers-reduced-motion`). +5. Enforce the **standalone contract**: no external `