Convex component adoption planner

Convex Component Adoption Planner

Use this skill when a private Convex app needs a serious answer to any of these:

• Should we adopt a specific Convex component?
• Which Convex component best fits a planned feature?
• How should a component integrate without creating duplicate ownership?
• Generate a fresh-session execution package for adopting or explicitly rejecting a component.

Core stance

• Always inspect the app's current durable owner before recommending a component.
• Prefer one canonical owner. If a component would create a second source of truth, recommend against it unless the plan is a full hard-cut replacement.
• Keep deterministic prep in the helper CLI. Keep architecture, ownership, and recommendation judgment in the model.
• Use live Convex docs first. If the user asks for the latest or current component state, fetch it.
• Ask remaining design questions one at a time with request_user_input, and include weighted scores from 0.0 to 10.0 for each option.

Start here

1. If the component is not already fixed, fetch the live components index:

curl -s https://www.convex.dev/components/components.md

2. Run the helper first when available:

cargo run --manifest-path .agents/skills/convex-component-adoption-planner/scripts/convex-component-adoption-prep/Cargo.toml -- doctor --json
cargo run --manifest-path .agents/skills/convex-component-adoption-planner/scripts/convex-component-adoption-prep/Cargo.toml -- component @convex-dev/aggregate --feature bookmarks-intent-signals --json
cargo run --manifest-path .agents/skills/convex-component-adoption-planner/scripts/convex-component-adoption-prep/Cargo.toml -- scaffold @convex-dev/aggregate --feature bookmarks-intent-signals --json
cargo run --manifest-path .agents/skills/convex-component-adoption-planner/scripts/convex-component-adoption-prep/Cargo.toml -- scaffold @convex-dev/aggregate --feature bookmarks-intent-signals --stdout

Helper command contract

Use the Rust helper in this order:

1. doctor
   • checks whether the useful local tools are available
   • reports posture for curl, rg, opensrc, ctx7, gh, bunx, and cargo
   • use --json when you want machine-readable output
2. component <package>
   • normalizes the package into a docs slug
   • emits the live Convex docs URLs
   • emits the default plan output paths
   • emits suggested curl, opensrc, ctx7, and rg commands
   • pass --feature <slug> whenever the workstream is already known
   • pass --docs-slug <slug> if the Convex docs page does not match the inferred slug
   • pass --date YYYY-MM-DD or --plan-root <path> when you need a non-default output location
3. scaffold <package>
   • uses the same normalization rules as component
   • creates the target plan folder and writes stub PLAN.md plus CODEX_FULL_PROMPT.md
   • use --json to get created and skipped file paths back as structured output
   • use --stdout to preview the exact file contents without writing
   • use --force only when you intentionally want to overwrite existing stubs

Do not treat the helper output as the recommendation. It only prepares deterministic inputs and starter files.

3. Read the helper output, then gather exact repo context:

• packages/backend/package.json
• packages/backend/convex/convex.config.ts
• packages/backend/convex/schema.ts
• feature-specific backend modules and specs
• if the feature is already planned, the matching repo-local planning or prompt files under .agents/

4. Fetch the live component markdown page and inspect the package source:

curl -s https://www.convex.dev/components/<slug>/<slug>.md
opensrc path <package-name>

5. Optionally use extra tooling when it improves evidence quality:

• ctx7: useful for library documentation lookup and secondary cross-checks
• opensrc: preferred when internal implementation details matter
• bunx convex: optional for local CLI help or version-aligned Convex context
• gh: only if a GitHub issue or PR is part of the adoption decision

Do not hard-depend on any of these tools. Degrade cleanly when absent.

Workflow

1. Normalize the target component, feature scope, and intended output folder.
   • Prefer doctor then component.
   • Use scaffold --stdout when you want to inspect the starter package before writing it.
   • Use scaffold without --stdout when you are ready to create the package files.
2. Map the current durable owner in the target app before recommending anything.
3. Read only the exact repo files that govern the feature boundary.
4. Fetch live docs for the components index and the specific component page.
5. Inspect dependency source with opensrc when package behavior, tables, or APIs matter.
6. Check whether repo-local planning or prompt docs already define the feature. If they do, include alignment in the plan.
7. Ask one design question at a time with request_user_input only when local context cannot close the branch safely.
8. Produce the package described in references/package-spec.md.

Decision framework

Use this weighted scoring model for major choices:

Criterion	Weight
Solution leverage	35%
Application value	30%
Maintenance and cognitive load	25%
Architectural adaptability	10%

Rules:

• Recommended options should usually land at 9.0+ only when the tradeoff is genuinely strong.
• If every option is weak, say so and score them honestly.
• If a component conflicts with an existing durable owner, that conflict is usually a decisive penalty.

Required outputs

Read references/package-spec.md before writing final package files.

Default output location:

.agents/plans/YYYY-MM/MM-DD/convex-components/<component-slug>/

Required files:

• PLAN.md
• CODEX_FULL_PROMPT.md

For a rejection decision, still emit the same package, but make PLAN.md a definitive non-adoption memo and make CODEX_FULL_PROMPT.md an execution prompt for future re-evaluation or confirmed rejection.

Question style

When a user wants to work interactively or says grill me:

• Ask one question at a time.
• Provide exactly 2-3 mutually exclusive options.
• Put the recommended option first.
• Include a short weighted score summary in each option description.
• Resolve packaging, ownership, migration, and prompt-alignment branches before writing the package.

What not to automate

• Final recommendation
• Duplicate-ownership analysis
• Hard-cut migration judgment
• Whether a planned feature should stay app-owned or move to a component
• Prompt-package alignment decisions

Those stay in the model.

The helper can scaffold stub PLAN.md and CODEX_FULL_PROMPT.md files, but it must not decide the recommendation or architecture.

Examples

Evaluate one candidate:

curl -s https://www.convex.dev/components/components.md
cargo run --manifest-path .agents/skills/convex-component-adoption-planner/scripts/convex-component-adoption-prep/Cargo.toml -- component @convex-dev/aggregate --feature bookmarks-intent-signals --json
cargo run --manifest-path .agents/skills/convex-component-adoption-planner/scripts/convex-component-adoption-prep/Cargo.toml -- scaffold @convex-dev/aggregate --feature bookmarks-intent-signals --json
cargo run --manifest-path .agents/skills/convex-component-adoption-planner/scripts/convex-component-adoption-prep/Cargo.toml -- scaffold @convex-dev/aggregate --feature bookmarks-intent-signals --stdout

Overwrite an existing starter package intentionally:

cargo run --manifest-path .agents/skills/convex-component-adoption-planner/scripts/convex-component-adoption-prep/Cargo.toml -- scaffold @convex-dev/aggregate --feature bookmarks-intent-signals --force --json

Use optional Context7 support:

ctx7 library convex "components aggregate"
ctx7 docs /convex-dev/convex "aggregate component patterns"

Install the helper locally for repeated use:

make -C .agents/skills/convex-component-adoption-planner/scripts/convex-component-adoption-prep install-local
convex-component-adoption-prep doctor --json
convex-component-adoption-prep component @convex-dev/aggregate --feature bookmarks-intent-signals --json
convex-component-adoption-prep scaffold @convex-dev/aggregate --feature bookmarks-intent-signals --json
convex-component-adoption-prep scaffold @convex-dev/aggregate --feature bookmarks-intent-signals --stdout