Storytime Education Reference Package

Source Excerpt

Overview

The Storytime Education Reference Package is a structured wiki guidance system that enables Storytime to generate age-appropriate, subject-specific educational content without requiring users to specify topics or criteria manually. It consists of per-subject, per-grade guidance files organized under wiki/wiki/education/storytime/, shared reference documents, and a subject/grade map.

Architecture

Location: wiki/wiki/education/storytime/

Structure:

• README.md — Package overview and runtime behavior
• subject-grade-map.md — Maps each supported subject/grade pair to its guidance file
• inference-policy.md — Rules for how Storytime interprets guidance files at runtime
• qa-rubric.md — Quality assurance rubric for evaluating generated stories
• shared/ — Cross-subject reference documents (grade-bands, integration patterns, safety)
• <subject>/<grade>.md — Subject-specific, grade-level guidance files

File naming convention: education/storytime/<subject-slug>/<grade-slug>.md

Example: education/storytime/math/grade-3.md

Supported Subjects (10)

Supported Grades (10)

Total Scope

100 subject/grade files (10 subjects × 10 grades) + 7 shared documents (README, subject-grade-map, inference-policy, qa-rubric, grade-bands, integration patterns, safety) = 107 files total.

Buildout Methodology

The package was built out using concurrent work across the full agent fleet (Julius, Octavius, Reacher, Cypher). The buildout spec is at bedtime-stories/artifacts/storytime-education-reference-package-spec.md.

Execution Strategy

Tasks were organized into blocks of ~17–20 tasks each, dispatched sequentially through the concurrent work scheduler:

Progress: 37/109 tasks complete (34%), 72 remaining.

The full task manifest is at artifacts/storytime-education-package-block-manifest.md.

Operational Lessons (June 7, 2026)

Timeout Bottleneck

The concurrent work scheduler has a hardcoded 20-minute per-task timeout (max_task_seconds: 1200). This proved insufficient for large content generation tasks producing 2,000+ word guidance files.

Observed behavior:

• Workers (Octavius, Reacher, Cypher) produced complete output files but timed out during the post-task diff review step.
• The supervisor entered a stuck state with quarantined workers and could not auto-collect outputs.
• Manual intervention was required: kill supervisor/workers, then force-collect and deploy from the outputs/ directory.

Agent performance differences (local inference, 2026-06-07):

Workaround: Accept timeouts, wait for file generation, then manually collect outputs. The files themselves are valid — the timeout affects only the diff-review step.

Longer-term fixes to evaluate:

1. Increase max_task_seconds in the scheduler (currently not exposed as a CLI flag).
2. Reduce output size requirements per task (split larger files into sub-tasks).
3. Exclude Julius (slowest local model) from content generation blocks, use only for coordination/review.

Scheduler Recovery Pattern

When the supervisor is stuck with quarantined workers but outputs exist:

1. Kill supervisor and worker processes (local + remote via SSH).
2. Verify output files exist in outputs/ directory.
3. Copy outputs to target location manually.
4. Update the block manifest to reflect completion.

This pattern was used successfully for Block 2 (Math + Spelling).

Planning Phase Duration

Octavius's planning phase for the initial ~99 task packet required ~5–10 minutes of processing. The planning prompt combined the Julius planner brief (~9KB) plus spec content (~13KB total). Smaller blocks (17–20 tasks) plan in seconds.

Quality Standards

Every guidance file must contain:

1. YAML frontmatter — title, type, subject, grade, status, tags, related links
2. Runtime Summary — narrative description of how to teach this subject at this grade level
3. Default Topic Families — 3–8 coherent topic groups with use-when, core idea, good story actions, natural objects/settings, and avoid list
4. Evaluation Criteria — what constitutes a good story response for this subject/grade
5. Grade Strategy — calibration to cognitive/developmental expectations
6. Source citations — links to related wiki pages and source guidance

The QA rubric (qa-rubric.md) defines the acceptance test: running a sparse seed and a detailed seed through Storytime with blank topic and blank criteria, verifying the generated story contains specific topics, measurable criteria, defined concepts, and grade-appropriate language.

Current State (as of 2026-06-08)

• Block 1 complete: All science files and shared documents deployed to wiki/wiki/education/storytime/.
• Block 2 complete: All math and spelling files deployed.
• Block 3 in progress: Reading and writing tasks launched; workers generating content.
• Blocks 4–5 pending: History, social studies, art, music, life-skills, and consolidation tasks awaiting dispatch.

Spec Location

The authoritative specification is at bedtime-stories/artifacts/storytime-education-reference-package-spec.md. It defines the full architecture, file structure, runtime behavior, and acceptance criteria.

Related Work

The education reference package is part of the broader Storytime project, which also includes:

• Theme reference package — Storytime themes (separate spec and buildout)
• Application architecture — Python backend behind Cloudflare Tunnel (see storytime/architecture-decision-2026-06-05)
• Source guidance documents — Library copies of education and children's-story guidance reviewed during planning