Wizard Development

Wizard development

Ask who owns the concern and what they should need to understand to change it. Product knowledge belongs behind typed configuration boundaries; runner and UI infrastructure should consume those boundaries.

Execution policy and model admission

• Pi is the default choice for new work. Harness choice and model provider are separate: Pi supports gateway-backed Anthropic and OpenAI transports.
• Prefer orchestration. A seed agent plans work, then task agents execute focused conversations. Start from metrics and its context-mill flow.
• Linear is for very simple tasks and legacy support. Composed program sub-runs are also structurally clamped to linear; orchestration cannot nest through that seam.
• Anthropic Agent SDK remains supported as a legacy fallback, deprecated as the default. Retain it for major Pi vulnerabilities or missing support for new Anthropic models.

DEFAULT_BINDING selects Pi + linear for a program whose config sets no binding; flags and development overrides sit on top. Set new bindings explicitly. Migrating an existing program requires checking its flow, tasks, and lifecycle hooks; changing the default constant alone is insufficient. Both harnesses implement run and runTask.

Adding a model or effort is a cross-repository change:

1. Define the Wizard model ID and capabilities in constants and models; select it through the switchboard or supported context-mill stage metadata.
2. Check the PostHog mint's WIZARD_MODEL_ALLOWLIST and allowed efforts. The token's policy is enforced by the gateway; a local constant or CLI override cannot authorize a model.
3. Check the gateway's provider/catalog support and required Wizard system-prompt policy, including the security-triage request shape. A model not supported by that infrastructure needs a coordinated gateway/mint change before use.
4. Verify the chosen harness transport and effective effort with the same admission policy used by the target environment.

Local commandments provide runtime and tool guidance. They do not replace the gateway's required safety prompt. Keep gateway policy owned there rather than copying it into skills. Do not infer per-model effort authorization merely from the local capabilities table.

Choose the extension surface

• For a framework, follow adding-framework-support. Detection is pure; use bounded filesystem helpers and preserve specific-before-generic ordering.
• For a capability, follow adding-skill-program. Prefer a context-mill command within an existing family when that is sufficient. A native command needs a command module in src/cli/commands/ and registration in runCli (src/cli/index.ts), as well as program registration.
• For a command that runs no agent, such as mcp add or doctor, follow Add a tool. A tool never goes through runProgram, and no program imports one.
• For screens or primitives, follow ink-tui. A program's flow in src/tui/programs/<id>/ drives its screen sequence. Programs never use the UI; they get a runner context. TUI code takes the store it reports through as an argument, and session mutations use store setters that emit changes.
• For headless exploration, follow exploring-the-wizard. Drive current legal actions and inspect error outros and pending questions throughout execution.

For a new concern, first look for an existing typed surface. Add an abstraction only when it gives a real owner a smaller, reusable boundary.