Oak Open Curriculum Ecosystem

The Oak National Academy Open Curriculum, delivered three ways: a Model Context Protocol (MCP) app that puts Oak inside ChatGPT, Claude, Copilot, and Gemini — the AI assistants teachers already use; engineering tools for the wider ecosystem to build with — a generated, type-safe TypeScript SDK, a semantic search service, graph tools generated from Oak data, and evidence surfaces grounded in the wider education sector; and an openly documented framework for agentic engineering that delivers AI-amplified innovation without trading away rigour or excellence.

We're turning Oak's open curriculum into AI-native infrastructure — for teachers and the wider ecosystem — and transforming how we build and curate digital products, agent-first, to do it well.

Everything here serves the same ends: helping teachers find, adapt, and use high-quality curriculum resources; helping the organisations that serve schools build better tools, faster; and giving the wider world of education — sector bodies, edtech, and the AI platforms now working in classrooms — open components, open data access, and an openly documented engineering practice to build on. Public goods, built in the open.

Building capabilities. Representing knowledge as graphs is a strength we apply across domains — Oak's curriculum, the EEF evidence surface, AI-enhanced development, and how we run our own work.

Vision and strategy: Start with VISION.md — the two-part vision (Oak's curriculum made AI-native for teachers and the ecosystem; and how we build and curate it, agent-first). Then the strategy — the diagnosis, the three value streams, and how we'll know it's working. For the live delivery roadmap, see the release-planning corpus (the prior estate is conserved in the 2026-07 backlog).

Current status: Invite-Only Alpha — The alpha MCP app server is live at curriculum-mcp-alpha.oaknational.dev.

This is how we make Oak's openly licensed, fully sequenced, fully resourced curriculum easier to build on. We provide the Oak Curriculum SDK; the canonical MCP server, both an end-user app surface and a developer tool; the OpenAPI-to-MCP server pipeline; hybrid semantic search; and knowledge-graph surfaces — modular building blocks for education applications.

We also explore what's possible with MCP Apps in the AI assistants teachers already use — the canonical target platforms: ChatGPT, Claude, Copilot, and Gemini, and others. AI assistants can search Oak's curriculum and explore lessons, units, threads, sequences, and other structured content — helping teachers find, adapt, and use high-quality curriculum resources.

We also develop a reusable, self-improving Practice for agentic-first engineering: a plain-text framework that lets agents from major vendors collaborate, keep learning, and keep operational knowledge in the repository where it stays useful.

Putting Oak inside the AI assistants teachers already use, giving the wider ecosystem the tools to build with Oak curriculum content, and the openly documented Practice that delivers AI-enhanced innovation are three co-equal value streams — none secondary. Beyond Oak-hosted products, we publish a deliberate set of reusable sector components — the OpenAPI-to-MCP pipeline, SDK-generation patterns, hybrid-search tooling, MCP and MCP App scaffolds, graph projection conventions, and the openly documented Practice — so other organisations can lower the cost of building curriculum-aware applications without starting from scratch. The canonical inventory and scope for each asset are set out in What This Repo Provides below.

Product owners, school leaders, non-technical evaluators — you don't need to read the technical content below. Start with:

• VISION.md — the two-part vision: what this project delivers (for teachers and the wider ecosystem), and how we build and curate it agent-first; why it matters and the investment case
• Strategy — the diagnosis, the three value streams (app, tools, framework), the alignment to Oak's goals, and how we'll measure success
• Curriculum Guide — Oak's curriculum structure explained in plain language
• Progress update (April 2026) — what has been delivered, what is next, and why it matters; newer reports land in .agent/reports/

Developers and AI agents

• New here? — open an agent session and run /oak-under-the-hood; the orientation lens works out whether you want a quick answer, an overview, or a guided hands-on walk that can set up your machine, and meets you there
• Developers — continue to Quick Start below
• Oak teammates joining via Claude Code (or another AI coding agent) — Quick Start as above, then MCP servers for contributors for the sanctioned MCP set
• AI agents — read the start-right-quick workflow, then AGENT.md, then scan the five foundational ADRs — the architectural source of truth

Working with agents

This repository is designed for agentic development. Start agent sessions by naming the relevant start-right workflow and the outcome you want. The start-right workflow grounds the agent in the repo's live rules, plans, claims, comms, and git state before it acts.

For Claude Code, Cursor, Gemini, or another slash-command surface, a single agent session might start with:

/oak-start-right-quick find the most frequent user-impact bug from Sentry,
create a plan for resolving it, then execute it

For a coordinated team:

/oak-start-right-team you are part of a team of agents working on the
knowledge graph enhancement plan, please continue

For existing threads, prefer a pointer to the thread continuation record rather than restating live state in the prompt:

/oak-start-right-team continue agentic-engineering-enhancements from
.agent/memory/operational/threads/agentic-engineering-enhancements.next-session.md.
Treat this opener as a hypothesis until live grounding confirms it.

In Codex, use the same skill names through /skills or $skill-name mentions:

$oak-start-right-team continue agentic-engineering-enhancements from
.agent/memory/operational/threads/agentic-engineering-enhancements.next-session.md.
Treat this opener as a hypothesis until live grounding confirms it.

Use oak-session-handoff at the end of a meaningful solo session so the next agent inherits the real state rather than a chat transcript guess. In team sessions, oak-start-right-team should name the closeout owner; only that owner runs the full handoff, while other team members leave boundary-scoped closeout notes.

Browse the documentation by section: Foundation (vision and the agentic engineering system) · Governance (development, TypeScript, testing, accessibility, security) · Architecture (ADRs, OpenAPI pipeline, provider system) · Engineering (workflow, tooling, extending) · Operations (env vars, troubleshooting, runbook index) · Domain (curriculum data) · Docs index.

What This Repo Provides

Three capabilities, powered by three open education data sources:

Together, shipped products and reusable sector-facing components are the pillars of compositional curriculum intelligence, framed in depth in VISION.md; hosted surfaces versus reusable components are distinguished in Sector reusable components below.

Sector reusable components

Partners and external builders should anchor adoption claims on the reusable fabric enumerated here — the OpenAPI-to-MCP pipeline, SDK generation patterns, hybrid-search tooling, MCP/MCP App scaffolds, graph projection conventions, and the Practice — versus Oak-hosted APIs and deployments. Supporting playbooks and partner obligations grow from .agent/plans-backlog-2026-07/sector-engagement/current/sector-reusable-components-adoption.plan.md.

Data Sources

This repository integrates three open education data sources, each answering a different question that teachers ask:

Together these sources enable evidence-grounded curriculum discovery: AI agents can search for content (Oak API), understand where it fits in the curriculum structure (ontology), and recommend evidence-backed teaching approaches (the EEF Toolkit — openly licensed material from an independent, external organisation, brought together with Oak's own). They also equip internal Oak teams and external builders with high-quality integration primitives spanning curriculum API access, MCP, search, ontology alignment, and evidence surfaces. Organisational reuse of Oak's delivery patterns—not merely calling the upstream REST API—is set out above in Sector reusable components. See ADR-157 for the integration architecture and LICENCE-DATA.md for full licence terms.

MCP Server Capabilities

The MCP servers expose curriculum data through the three MCP primitive types:

• Tools (model-controlled): 37 curriculum tools (24 generated from the OpenAPI schema plus 13 aggregated compositions) covering search/browse/fetch flows, orientation via get-curriculum-model, the curriculum graph tools (get-thread-progressions for year-ordered sequences, get-prior-knowledge-graph, get-misconception-graph, get-keyword-graph), EEF evidence, download-asset, and the user-search pair. The AI decides when to use them. See apps/oak-curriculum-mcp-streamable-http/README.md as the canonical count.
• Resources (application-controlled): The curriculum model, a getting-started guide, and the EEF evidence-interpretation guide as pre-loadable context for MCP clients that support resource injection. The curriculum graphs are deliberately tool-only — served anchored and bounded by the graph tools rather than as whole-corpus dumps.
• Prompts (user-controlled): Seven workflow templates (find-lessons, lesson-planning, explore-curriculum, learning-progression, curriculum-mapping, adapt-lesson, continue-progression) that guide users through common curriculum tasks — including the position-anchored entry point: state what your class just covered and plan the next step from Oak's sequence, building on what came before.

The standalone stdio workspace has been retired and removed. The canonical MCP server workspace is now apps/oak-curriculum-mcp-streamable-http/; any future stdio support is expected to come from a separate stdio entry point generalised from that workspace rather than a parallel standalone app. See the HTTP MCP server README, ADR-123, and ADR-128.

Quick Start

Prerequisites

• Node.js 24.x — install via nvm or fnm, then run nvm use or fnm use to activate the version in .nvmrc
• pnpm — run corepack enable (ships with Node.js) to auto-install the pinned version
• bun (optional, for pnpm dev:widget-in-host) — install via bun.sh
• lsof (optional, for apps/oak-curriculum-mcp-streamable-http/scripts/restart-dev-server.sh) — pre-installed on macOS; on Debian/Ubuntu use sudo apt install lsof; source/build instructions at github.com/lsof-org/lsof
• GNU timeout (optional, for the agent-collaboration comms watcher's self-termination guard) — the canonical watcher is wrapped in timeout/gtimeout so a watcher whose agent has gone away cannot linger as an orphan process. macOS: brew install coreutils (GNU coreutils; the binary installs as gtimeout); Debian/Ubuntu and most Linux ship it with GNU coreutils as timeout (sudo apt install coreutils if missing). The watcher runs un-guarded if neither binary is on PATH, so it is needed only to enforce the dead-watcher cleanup (see comms-all-channels-watcher and friction F-101).
• sentry (optional, for dev-time Sentry issue triage, event inspection, and Sentry Seer) — install only when you need local Sentry operator tooling; see Sentry CLI usage for the sentry-cli vs dev-sentry split and workspace invocation details.
• Linear plugin (Claude Code users) — issue tracking through Linear's hosted MCP server. The tracked .claude/settings.json enables linear@claude-plugins-official, so Claude Code offers to install it on first launch in this repository — accept the prompt, then authenticate with /mcp. The full sanctioned MCP set is listed in MCP servers for contributors.
• MCPJam (optional, for MCP server development and validation only) — inspects, runs conformance checks, and authors/runs evals against the MCP server; backs the optional mcpjam entry in .mcp.json. Installed by pnpm install; run commands with pnpm exec mcpjam <command>, the inspector GUI with pnpm dlx @mcpjam/inspector@latest, and authenticate for the hosted eval and project features with pnpm exec mcpjam login. The companion mcp-inspector skill installs at the machine level via pnpm dlx skills add mcpjam/inspector --skill mcp-inspector.

Install and verify

git clone https://github.com/oaknational/oak-open-curriculum-ecosystem.git
cd oak-open-curriculum-ecosystem
pnpm install
pnpm test && pnpm type-check && pnpm lint

If these pass, your toolchain is working. No API keys are required for unit tests, type-checking, linting, or building.

Before your first push: install gitleaks (brew install gitleaks on macOS). The pre-push hook runs a secrets scan and will block pushes if gitleaks is not installed.

Get an API key (optional)

Many tasks work without environment variables. To run dev servers, integration tests, or search workflows, you need an Oak API key:

1. Request a free key: https://open-api.thenational.academy/docs/about-oaks-api/api-keys
2. Copy the example environment file for the workspace you are running and add your key there:

# HTTP MCP server
cp apps/oak-curriculum-mcp-streamable-http/.env.example \
  apps/oak-curriculum-mcp-streamable-http/.env.local

# Search CLI
cp apps/oak-search-cli/.env.example apps/oak-search-cli/.env.local

# Edit the relevant .env.local and set OAK_API_KEY=your_key_here

See environment variables guide for Elasticsearch, Clerk, and other service credentials.

Next steps

The Architecture section below summarises the schema-first design and key directories. For the development process, commit conventions, and quality expectations, see CONTRIBUTING.md. Each workspace README provides area-specific setup (see links in the capability table above).

For the shape of the curriculum data and per-key-stage variance, see the Curriculum Guide and Data Variances. For how MCP tools execute against the OpenAPI schema at runtime, see openapi-pipeline.md → Schema-First Tool Invocation.

Key Commands

Daily development:

pnpm test           # Unit + integration tests
pnpm type-check     # Type-check all workspaces
pnpm lint           # Read-only lint verification
pnpm build          # Build all workspaces
pnpm sdk-codegen    # Regenerate SDK + MCP artefacts from OpenAPI

Widget development (from apps/oak-curriculum-mcp-streamable-http/):

pnpm dev:widget          # Standalone widget dev server with token live-reload
pnpm dev:widget-in-host  # Widget rendered inside MCP Apps basic-host (requires bun)
pnpm test:widget         # Widget unit + integration tests
pnpm test:widget:ui      # Playwright visual tests (light + dark themes)
pnpm test:widget:a11y    # Playwright axe-core WCAG 2.2 AA gate

Full verification:

pnpm make           # Full convenience pipeline with auto-fix steps; review file changes afterwards
pnpm check          # Canonical full verification gate: clean rebuild + tests + docs + formatting/linting fixes
pnpm fix            # Auto-fix: format + markdownlint + lint
pnpm clean          # Remove build artefacts (dist/, .turbo)

Architecture

Everything flows from the OpenAPI schema:

1. OpenAPI Schema (single source of truth)
2. → TypeScript SDK (generated at pnpm sdk-codegen)
3. → MCP Tools (generated from the same schema)
4. → Type-safe everything (no manual type definitions, no runtime assertions)

The Cardinal Rule: If the OpenAPI schema changes, running pnpm sdk-codegen updates the SDK, types, validators, and MCP tools automatically. Zero manual intervention.

Search uses Elasticsearch with 4-way reciprocal rank fusion (ELSER sparse vectors, BM25, synonym expansion, and phrase boosting) to achieve high-accuracy retrieval across curriculum structures. See the search architecture for details and the OpenAPI pipeline for the generation architecture.

Workspace Summaries

Apps:

SDKs:

Core and Libraries:

Core packages:

Libraries:

Design:

Architectural Decision Records (ADRs) are the architectural source of truth. These three foundational ADRs define the schema-first approach that underpins the codebase:

• ADR-029 — No manual API data structures
• ADR-030 — SDK as single source of truth
• ADR-031 — Generation-time extraction

See the full ADR index for all decisions (start with the "5 ADRs in 15 Minutes" block).

Architectural invariants

Six stable, ADR-backed properties make this repository what it is. Each links to its authoritative doc, which always carries the detail:

1. The SDK updates itself from the API spec — when the upstream OpenAPI schema changes, regeneration brings every workspace into alignment with zero manual type work (the Cardinal Rule above; OpenAPI pipeline).
2. Two data feeds, both deliberate — the live API powers the SDK and MCP tools (OpenAPI pipeline), while bulk-downloaded curriculum data is the source of truth for search ingestion and graph derivation (semantic search architecture).
3. The curriculum graphs are derived from the bulk data — prior knowledge, misconceptions, keywords, and progressions served as anchored graph tools (graph-stack topology, ADR-173).
4. EEF evidence grounds the pedagogy — the Teaching and Learning Toolkit is integrated for evidence-based support (Data Sources).
5. The bulk data populates the semantic search — ingestion builds the search indices from it (ingestion guide).
6. The Search SDK serves both sides — creating and operating search instances as well as querying them (Search SDK).

Engineering Practice

This repository began as an exploration of what co-pilot style AI support could provide, but evolved rapidly into an agent-first engineering system. As of February 2026, for at least the previous six months, every line of code, configuration, and documentation has been written entirely by agents. Humans focus on system design: defining guardrails, architectural constraints, quality gates, and reviewer workflows; then providing direction and corrective feedback.

The result of this approach is the Practice — a transferable, self-improving system of principles, structures, specialist agents, and tooling that governs how work happens. The Practice is not a static rulebook; it contains a self-reinforcing improvement loop that learns from every session and evolves its own governance. The core cycle:

1. Capture — agents continuously log mistakes, corrections, and patterns to a session napkin
2. Refine — periodic distillation extracts high-signal entries into a curated reference
3. Graduate — the consolidation workflow moves settled patterns into permanent documentation (ADRs, governance docs, READMEs)
4. Enforce — permanent docs become rules and directives that govern the next session's work

The loop is self-referential: it improves not just the product code but the Practice itself. Rules about rule creation, patterns about distillation quality, and insights about consolidation all flow through the same cycle.

The Practice also travels between repositories via a plasmid exchange mechanism — a package of seven portable files that carry the improvement loop to new contexts. Different repos stress-test the Practice against different work, surfacing learnings that travel back to the origin. If a repo already has a Practice, then the income Practice is analysed and the best parts are integrated into the incumbent Practice. This allows the benefits of the learning loop to be compounded through multiple repos, while allowing the Practice to adapt itself to suit the context of eac