Extending the wizard

Scope your work first

You're the driver, so open a PR! If your change might touch everyone else's program, ping us in #team-wizard-and-docs so we can assess the blast radius together. We don't want to block you, but we do want to keep the wizard from exploding.

You want to	How
Add a new program	Self-serve
Update your team's program	Self-serve
Change something that reaches across many products, or the core agent and shared code	Open an issue with a design pitch first. The Wizard & Docs TeamWizard & Docs Team and their agents help design it and provide context.

Where your change goes

Most changes to the wizard are a change to the context mill, not the wizard repo.

Point your agent here

Each repo has instructions written for coding agents. Start your agent with the ones that match your change.

Run it programmatically

Both the agent and programs run without a host, so a test, another agent, or a new surface can call them directly. These are simplified signatures. The source has the full types.

// The agent on its own, from '@agent'
runAgent(
  config: RunConfig, // what to run: prompt, binding, tools, commandments
  input: RunInput, // where: install directory, credentials, skill, flags
  options?: {
    onProgress?: (event: AgentProgress) => void // optional, never awaited
    interaction?: AgentInteraction // optional, answers wizard_ask
    signal?: AbortSignal
  },
): Promise<RunResult> // outcome, outro or failure, and a snapshot of the run

// A whole program, from '@programs'
runProgram(
  programId: string,
  input: {
    store: SessionStore // the run's state, built with buildSession()
    credentials?: ResolvedProgramCredentials
    config?: Partial<ProgramConfig> // laid over the registered config
  },
  options?: {
    credentials?: CredentialsProvider
    interaction?: AgentInteraction
    onProgress?: (progress: ProgramProgress) => void
    workflow?: ProgramWorkflowConnector // the host's confirm steps
    signal?: AbortSignal
  },
): Promise<ProgramRunOutcome> // outcome, one RunResult per agent run, report file

// Context mill content, from src/shared and src/agent
fetchSkillMenu(skillsBaseUrl): Promise<SkillMenu | null> // skill-menu.json
installSkillById(skillId, installDir, skillsBaseUrl, options) // into .claude/skills/<id>
loadAgentRegistry(skillsBaseUrl, flow): Promise<AgentRegistry> // one orchestrator flow from agent-menu.json

skillsBaseUrl is the latest context mill release on GitHub, or http://localhost:8765 for a local context mill.

Commands and skills

The wizard's commands come from context mill. A skill becomes a command when its config.yaml has a cli: block with role: command. For example, wizard audit events is the audit-events skill.

The wizard reads these commands from the latest context mill release when it runs. A new subcommand under an existing command only needs a context mill release.

A new top-level command also needs a wizard PR. The wizard registers each top-level command in src/cli/commands/. Ship the context mill PR first, so the skill exists before the wizard looks for it.

The command list is curated. A new role: command needs sign-off from a wizard maintainer, because a public command name is hard to remove.

Adding a program

A program is a folder in the wizard repo. To add one:

1. Create src/programs/<id>/ with an index.ts that exports its ProgramConfig, and a tsconfig.json copied from a sibling program.
2. Add it to PROGRAM_REGISTRY in program-registry.ts, and to the references in src/programs/tsconfig.json.
3. Optionally add screens in src/tui/programs/<id>/, a command file in src/cli/commands/, and a test/e2e.json so wizard CI can drive it.

The programs README has the full checklist, and the adding-skill-program skill walks an agent through it.

Worked example: wizard mcp-analytics

This command was added in four PRs. Copy its shape.

1. The skill: context-mill#202
2. The wizard command: wizard#731
3. The test apps: wizard-workbench#2158
4. The docs: posthog.com#17939

These PRs predate the current layout. The wizard command now goes in src/cli/commands/ instead of bin.ts, and the program lives in src/programs/ instead of src/lib/programs/.

Testing a new command

• Unit test in the wizard repo. Add a case to programs-cli.test.ts that checks the command registers in the right shape and runs the right skill.
• Test app in the workbench. Add an app under apps/ and an entry in apps/manifest.json, so CI can run the real agent against it. Add one app per distinct path the skill handles.
• Evals. Wizard CI grades each run against a rubric and scores it out of 5. The workbench apps are working examples of what good output looks like.

See Developing the wizard for how to run them.

Go deeper

• The cli: block schema
• Wizard AGENTS.md
• Programs README