Extend Keating without losing the teaching contract

Choose the smallest useful extension point

A teaching sequence belongs in a prompt or skill when it can use existing tools. A deterministic artifact transformation belongs in the core. A new model or execution environment belongs at the runtime boundary. A new learner interaction needs a shared contract and the appropriate client renderers.

Keeping these choices separate makes it possible to review what changed: the teaching instructions, the local algorithm, the permissions available to a model, or the experience the learner sees.

Write a teaching prompt or skill

pi/prompts/ contains workflows such as learn, diagnose, quiz, and bridge. Prompt templates carry metadata and use the topic argument in the body. pi/skills/adaptive-teaching/SKILL.md defines the broader teaching contract: diagnose, build intuition, repair misconceptions, ask for reconstruction, and probe transfer.

Preserve the interaction pause. A generated question should wait for the learner's submitted answer rather than continuing with its own answer. Use persisted artifacts when the workflow needs durable files; use inline learner interactions for the immediate teaching turn.

Add a command or artifact tool

Implement reusable artifact behavior in src/core/, connect project filesystem work through src/core/project.ts, and expose the operation through the CLI or Pi extension as appropriate. Update src/core/commands.ts when the command name, arguments, description, or supported surface changes; it drives generated help.

Keep root TypeScript imports compatible with NodeNext and use .js import extensions. Check browser-safe types and browser tool implementations when changing a shared core shape. Avoid introducing Node filesystem imports into browser paths.

Load a Pi package explicitly

Keating supports configured Pi package sources. The package command records additions in Keating's configuration and the runtime synchronizes them into its isolated Pi settings directory when launching. Use the package list to inspect what will load.

Pi extensions and skills can execute with local system access. Treat adding a package as installing code with that authority, and review its source and requirements before using it with learner data.

keating package recommended
keating package list
keating package add npm:pi-subagents
keating shell

# Equivalent shell management:
/packages list

Keep interaction contracts portable

A shared learner interaction affects more than its web component. Check the learner contracts, source mappers, web and mobile renderers, terminal consumer, storage and action handling, and representative fixtures. Update generated runtime files when their source contract changes.

Client differences should be explicit. A native mobile storage boundary, a terminal interaction, and a browser sandbox capability are not interchangeable merely because they use the same learner-facing concept.

Test the invariant, then the real boundary

Use Bun tests and existing fixtures for behavior that can be deterministic. Keep policy scalars within zero and one, practice counts integral from one to five, and weights normalized. Exercise domain-specific phases when you change lesson construction. Inject model runners and judges so the local suite does not depend on a hosted provider.

Model execution, browser behavior, packaging, and deployment need their own checks. Report which boundary a check exercised. Prompt evolution writes reports and evolved snapshots without silently replacing checked-in templates; activating a teaching revision still requires its independent evidence gates.