Skip to content

cianfhoghlaim/cianchosaint / .agents/skills/schema-codegen

schema-codegen

Unverified

Schema-Driven Codegen Pipeline

The canonical BAML → Zod → Convex → CopilotKit → AG-UI pipeline. Added by the 2026-08-13-web-monorepo-consolidation-and-agent-integration-v1 change (Phase O).

What this pipeline does

The pipeline takes the BAML .baml files at baml_src/ as the canonical source of truth and emits 5 categories of artifacts:

  1. TypeScript types + Zod schemas (baml_client/typescript/...)
  2. Convex table definitions (web/apps/oideachais-dashboard/convex/<stage>/<subject>.ts)
  3. CopilotKit v2 action registries (web/hono-api/src/routes/copilotkit/<stage>/<subject>.ts + web/apps/oideachais/src/lib/copilotkit/<stage>/<subject>.ts)
  4. AG-UI protocol event type wrappers (web/apps/oideachais/src/lib/ag-ui/<stage>/<subject>.ts)
  5. Per-subject TanStack Start routes (web/apps/oideachais/routes/<stage>/<subject>/{index,$topicId}.tsx)

The pipeline is idempotent — running it twice on the same input produces byte-identical output.

Quick start

# Run the full pipeline for all 60 subjects × 4 stages
mise run codegen:all

# Dry-run (preview without writing files)
mise run codegen:all:dry-run

# Run for one subject
mise run codegen:subject mathematics

# Run for one stage
mise run codegen:stage lc

# Run a single step (1-5)
bun run scripts/schema-codegen/index.ts --step 3

The 5 sub-generators

StepScriptOutput
1baml-to-ts.tsbaml_client/typescript/... + codegen-manifest.json
2convex-from-zod.tsweb/apps/oideachais-dashboard/convex/<stage>/<subject>.ts
3copilotkit-actions.tsweb/hono-api/src/routes/copilotkit/<stage>/<subject>.ts + web/apps/oideachais/src/lib/copilotkit/<stage>/<subject>.ts
4ag-ui-types.tsweb/apps/oideachais/src/lib/ag-ui/<stage>/<subject>.ts
5per-subject-routes.tsweb/apps/oideachais/routes/<stage>/<subject>/{index,$topicId,AGENTS}.tsx|md

The 60-subject matrix

The pipeline covers 60 subjects × 4 stages:

  • 14 LC subjects (Mathematics, Chemistry, Physics, Biology, English, Gaeilge, French, History, Geography, Business, Accounting, Art, Music, Computer Science)
  • 8 JC subjects (Mathematics, English, Gaeilge, Science, History, Geography, French, Business)
  • 9 GCSE subjects (Mathematics, English Literature, English Language, Biology, Chemistry, Physics, History, Geography, Modern Foreign Languages)
  • 15+ A-Level subjects (Mathematics, Further Mathematics, Chemistry, Biology, Physics, English Literature, English Language, History, Geography, Psychology, Economics, Business, Politics, Sociology, Modern Foreign Languages)

Each subject has:

  • 8 BAML extraction functions (ExtractCurriculumSyllabus, ExtractExamPaperLayout, ExtractMarkingScheme, ExtractCrossLinguistic, ExtractSyllabusDiagram, ExtractLearningOutcome, ExtractKeyTerm, ExtractTopicGraph)
  • 1 Convex table schema (with app + stage + subject field filter)
  • 13 CopilotKit actions (get_syllabus_topics, get_exam_papers, get_marking_schemes, get_topic_detail, get_cross_jurisdictional_equivalences, semantic_search, extract_syllabus_from_pdf, save_annotation, track_progress, get_study_plan, compare_curricula, get_glossary_term, extract_learning_outcome)
  • 1 AG-UI event types file (10 typed wrappers + 1 RunAgentInput + 1 Tools interface + 1 Event union)
  • 1 TanStack Start landing route + 1 topic detail route + 1 per-subject AGENTS.md

Configuration

FlagDescription
--subject <slug>Run for one subject (e.g. --subject mathematics)
--stage <stage>Run for one stage (lc | jc | gcse | a-level)
--step <1-5>Run a single step
--dry-runPreview without writing files
--root <path>Override the repo root

Key sources

PathWhy it matters
scripts/schema-codegen/index.tsThe orchestrator (calls the 5 sub-generators)
scripts/schema-codegen/baml-to-ts.tsStep 1 — BAML → TypeScript types
scripts/schema-codegen/convex-from-zod.tsStep 2 — Convex table definitions
scripts/schema-codegen/copilotkit-actions.tsStep 3 — CopilotKit v2 actions
scripts/schema-codegen/ag-ui-types.tsStep 4 — AG-UI 17-event-type wrappers
scripts/schema-codegen/per-subject-routes.tsStep 5 — TanStack Start routes
baml_src/<area>/<stage>/<subject>/The BAML source (the canonical truth)
scripts/_zod-from-duckdb.tsThe DuckDB → Zod mapping (the existing R30 codegen)
scripts/schema-generate.tsThe existing lineage + DuckDB → Zod codegen (extended by step 2)
scripts/schema-validate.tsThe CI drift gate (validates schema codegen output)

Adjacent specs

DO NOT

  • Never edit the generated files by hand — re-run the pipeline
  • Never add a BAML function without re-running mise run codegen:all
  • Never bypass the pipeline by writing artifacts directly
  • Never add per-subject files outside the canonical structure

Skill pointers

SkillWhen to load
centralized-registryThe model + schema registry that the codegen reads from
schema-codegenThis skill (the schema-driven codegen pipeline)
tanstack-startTanStack Start file-based routing
bamlThe BAML extraction framework
cocoindexThe CocoIndex v1 embedding layer
agentic-frontend-frameworksTanStack Start + CopilotKit + AG-UI + Hono + Convex
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall