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/services/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/services/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. metadata.name is the framework's label once detection or the picker settles it.

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; metadata.gatherContext collects framework context. When the gathered context names a more specific variant, return its label from metadata.getDetectedFrameworkLabel(context); detection sets the label through its context. Return the variant's stable id from metadata.getVariant(context), which becomes the project's variant trait. Framework configs never use the UI. 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 context-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. ui.getOutroNextSteps and analytics.getEventProperties have no consumer. 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.