adding-skill-program

Adding a Skill-Based Program

A skill-based program installs a context-mill skill and runs the agent against it. Examples in the codebase: the audit program (clean factory call), the revenue-analytics program (factory + custom intro screen + detect step).

Before reading this, read wizard-development/SKILL.md for the architectural context — particularly principle 4 ("New capability is a new program, not a new branch").

Architecture

The wizard's runner pipeline is fixed. What varies between programs is a ProgramRun configuration object that controls the skill ID, prompt, success message, abort cases, and post-run hooks. A ProgramConfig ties together: the CLI command, the step list, and the ProgramRun. The program registry derives all downstream wiring — CLI subcommands, TUI programs, the router — from a single array. Adding a program is configuration, not code.

The common case: createSkillProgram

For programs that just install a skill and let the agent run it (most programs), use the factory in agent-skill/index.ts:

// src/lib/programs/error-tracking/index.ts
import { createSkillProgram } from '../agent-skill/index.js';

export const errorTrackingConfig = createSkillProgram({
  skillId: 'error-tracking-setup',
  command: 'errors',
  flowKey: 'error-tracking',
  description: 'Set up PostHog error tracking',
  integrationLabel: 'error-tracking',
  successMessage: 'Error tracking configured!',
  reportFile: 'posthog-error-tracking-report.md',
  docsUrl: 'https://posthog.com/docs/error-tracking',
  spinnerMessage: 'Setting up error tracking...',
  estimatedDurationMinutes: 5,
  requires: ['posthog-integration'],  // optional: prior programs that must run first
});

Then register it in one place:

1. src/lib/programs/program-registry.ts — add to PROGRAM_REGISTRY array

That's the entire program. bin.ts, the store, the agent runner, the router, and the screen sequences (src/ui/tui/screen-sequences.ts) all derive their wiring from the registry automatically. Don't add a yargs command. Don't add a runner function. Don't touch bin.ts. The ProgramId union type updates itself from the registry contents.