posthog 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/frameworks. Framework-specific detection, context, environment conventions, and UI metadata belong here. Integration instructions and examples belong in context-mill.
- 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.
- Add the config under
src/frameworks/<name>/<name>-wizard-agent.ts. Use atypefor framework context so it satisfiesRecord<string, unknown>. Export the config; the integration program already supplies execution. - 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
| Starting point | Pattern to reuse |
|---|---|
| Next.js | hasDeclaredDependency from utils/package-json, tryGetPackageJson from utils/setup-utils, and router setup questions |
| Django | Python project files, context gathering, and Python package-manager detection |
| Laravel | Composer and framework-specific filesystem signals |
| Rails | Gemfile detection and Ruby conventions |
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.