adding-framework-support

Adding Framework Support

Read wizard-development for the shared design policy and gateway contract. New agent work uses Pi and prefers the orchestrator; adding a framework extends the integration program without creating its own runner or changing existing routing defaults.

Extend the framework configuration

Start with FrameworkConfig and a nearby example under src/programs/frameworks. Framework-specific detection, context, environment conventions, and UI metadata belong here. Integration instructions and examples belong in context-mill.

1. Add the integration to Integration. Its order controls first-match detection and the framework picker. Keep specific frameworks before language fallbacks and generic Node last; preserve the overlap rules in the detection checks.
2. Add the config under src/programs/frameworks/<name>/<name>-wizard-agent.ts. Use a type for framework context so it satisfies Record<string, unknown>. Export the config; the integration program already supplies execution.
3. Import the config into FRAMEWORK_REGISTRY. The display label comes from metadata.name.

Read the current interface for the complete required fields. In particular, detection.detectPackageManager is required: reuse an adapter from package-manager detection. Use metadata.setup.questions for unresolved project variants; gatherContext collects framework context. Optional notices and extra MCP servers also belong in metadata.

Use usesPackageJson: false for frameworks without a package.json dependency. Their required getVersion callback can return undefined. Minimum-version checking requires both minimumVersion and getInstalledVersion; unknown versions pass. Context detection returns unsupported-version data for the integration UI rather than aborting itself.

Detection and examples

Use bounded filesystem helpers for project scans and reads. They bound traversal and skip dependency/build directories; add framework-specific exclusions with extraIgnore. Keep complex parsers and detectors beside the config so they can be checked independently.

Complete the content side

Ensure context-mill supplies the matching integration reference and task-skill variants for the framework. A registry entry alone does not provide integration knowledge. The orchestrator resolves framework variants from the skill menu and rejects missing task variants; see the orchestrator runner.

Keep project-specific facts in configuration and reusable integration guidance in that content. Model IDs, reasoning efforts, and gateway-required system prompts follow the cross-repo contract in wizard-development; a framework config cannot enable a new gateway model.

Verify the changed behavior

Check detection against the target framework and the closest overlapping framework/fallback. Reuse the existing detection checks; add a focused case only for behavior they do not cover. Confirm package-manager selection and matching content-mill variants. For an end-to-end run, use a disposable test app and the exploration guide.

For prompt, environment-upload, or outro changes, inspect the current integration program and the selected sequence. Some fields remain in the interface without a current consumer: getOutroNextSteps is not used by the integration outro. Linear post-run/outro hooks are not shared by the orchestrator; see the program guide.

Use the proportionate validation guidance in wizard-development. Documentation-only changes need source/link checks, not an agent run.