docs: agent-native initiative — spec, plan, and project workspace - #29688
Merged
Conversation
Adds docs/plans/agent-native/: a spec and 10-task plan for making Prisma ORM agent-native. Covers skill distribution (install on init, one-time interactive offer on generate reusing the NPS survey infrastructure), the AI safety checkpoint follow-ups, the prisma/skills content roadmap (configuration routing, generate-after-schema-change plugin, troubleshooting, API pitfalls with engine-verified semantics, performance, platform CLI disambiguation), and unhiding the typedSql preview feature. Also records the NPS survey infrastructure, the prisma mcp command, and the docs/plans convention in AGENTS.md.
…ive plan Prisma 7 does not ship a MongoDB connector, so MongoDB users have no v7 upgrade path; the supported future is Prisma Next. Task 011 adds a prisma-mongodb-upgrade skill to the prisma/skills workstream covering decision framing (migrate now vs stay on v6), schema/config/client migration mechanics, and hand-off to prisma-next's own skill cluster.
Adds projects/agent-native/ (spec, plan, design notes, trace journal) per the drive workflow convention. The spec carries the system-level intent (purpose, non-goals, cross-cutting requirements, transitional constraints, DoD); the plan composes four slices (init skill install -> generate skill offer as a stack; MCP safety audit and typedSql unhide in parallel) with Linear references (TML-2967..2973). Detailed task drafts live in docs/plans/agent-native/.
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughThis PR adds documentation-only content for the agent-native project. It introduces project-level spec, plan, design, task index, and task documents, plus AGENTS.md guidance and a drive spec README. It also adds slice-level specs, plans, briefs, verification notes, and orchestration records for the init-skill-install and generate-skill-offer slices, along with review, rollup, learning, retrospective, and unattended-decision records. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/plans/agent-native/001-init-skill-install.md`:
- Around line 17-20: The fenced shell example in the skill-install markdown is
missing a language hint, which is triggering markdownlint and hurting
readability. Update the command block to use a bash fence in the existing
example under the skill install instructions so the snippet is clearly
recognized as shell content.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 03d01579-dcea-4173-8f67-97522fe11a6a
📒 Files selected for processing (17)
AGENTS.mddocs/plans/agent-native/000-agent-native-index.mddocs/plans/agent-native/001-init-skill-install.mddocs/plans/agent-native/002-generate-skill-offer.mddocs/plans/agent-native/003-ai-safety-checkpoint.mddocs/plans/agent-native/004-skill-connection-config.mddocs/plans/agent-native/005-skill-generate-after-schema-change.mddocs/plans/agent-native/006-skill-troubleshooting.mddocs/plans/agent-native/007-skill-api-pitfalls.mddocs/plans/agent-native/008-unhide-typed-sql.mddocs/plans/agent-native/009-skill-performance.mddocs/plans/agent-native/010-skill-platform-cli-routing.mddocs/plans/agent-native/011-skill-mongodb-upgrade.mdprojects/agent-native/design-notes.mdprojects/agent-native/plan.mdprojects/agent-native/spec.mdprojects/agent-native/trace.jsonl
Contributor
size-limit report 📦
|
…spatch plan Opening rollup, unattended-decisions log (D1-D8), slice spec and 3-dispatch plan for init-skill-install (TML-2968). PR #29684 merged, so TML-2972 is done and S3 is unblocked.
…alt resolved D1 (runner) and D2 (Init wiring + yarn-1 fix) both SATISFIED with zero findings. D3 live runs falsified a spec assumption: skills@1.5.14 multi-agent installs never create the promised per-agent symlinks, so the install now passes --copy (decision D13); tagging ask and upstream bug report are preserved for the operator (D14, permission-gated). Decisions D9-D14 in unattended-decisions.md.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@projects/agent-native/slices/init-skill-install/briefs/d1-r1.md`:
- Around line 27-31: Update the `installSkills` brief so the example command
matches the final multi-agent install shape by including `--copy` alongside the
existing runner, agents, and `--skill '*' -y` flags. Keep the rest of the
detection and execution description unchanged, and make sure the command example
in the `installSkills` section reflects the amended CLI form.
In `@projects/agent-native/slices/init-skill-install/plan.md`:
- Around line 26-30: The completion criteria in the init-skill-install plan is
missing Windsurf, while the dispatch checks only mention .claude/skills/ and
.agents/skills/. Update the spec in plan.md so the expected install targets
include Windsurf as well, and make sure the outcome/completion wording reflects
validating all required install destinations for the init flow.
In `@projects/agent-native/slices/init-skill-install/spec.md`:
- Around line 50-53: The spec currently implies the prisma/skills tagging
request has already been filed, but the decision log says it is still a
permission-gated deferral. Update the wording in the affected spec section and
the related downstream plan/briefs to state that the per-ORM-minor tagging ask
still needs operator action and is not yet a completed condition. Use the
existing install-source wording and any references to the skills repo/tagging
plan to keep the status consistent across the slice.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 1541ee86-c3e4-4408-88a7-b2a66ac9871b
📒 Files selected for processing (12)
projects/agent-native/learnings.mdprojects/agent-native/reviews/code-review.mdprojects/agent-native/rollups/2026-07-03-opening-rollup.mdprojects/agent-native/slices/init-skill-install/briefs/d1-r1.mdprojects/agent-native/slices/init-skill-install/briefs/d2-r1.mdprojects/agent-native/slices/init-skill-install/briefs/d3-r1.mdprojects/agent-native/slices/init-skill-install/briefs/d3-r2.mdprojects/agent-native/slices/init-skill-install/plan.mdprojects/agent-native/slices/init-skill-install/spec.mdprojects/agent-native/slices/init-skill-install/verification.mdprojects/agent-native/trace.jsonlprojects/agent-native/unattended-decisions.md
D3 R2 satisfied after the --copy amendment; slice scoreboard 2 PASS + 1 accepted deferral (AC-3, permission-gated external filings preserved in verification.md). Full trace through dispatch-end.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@projects/agent-native/slices/generate-skill-offer/briefs/d1-r1.md`:
- Around line 39-42: The gate command is using the wrong test runner for
nps.test.ts, which is Jest-only. Update the gate in
generate-skill-offer/briefs/d1-r1.md to use the shared package test helper in
packages/cli/helpers/run-tests.ts (for example via pnpm test with the shared
filter) so it runs both Jest and Vitest tests correctly, instead of invoking
vitest run on nps.test.ts directly.
In `@projects/agent-native/slices/generate-skill-offer/spec.md`:
- Around line 24-26: The installed-skill gate in the generate-skill-offer spec
is missing the `.windsurf/skills/prisma-*` location used by the init layout, so
the offer can be shown again after installation. Update the already-installed
check alongside the existing `skills-lock.json`, `.claude/skills/prisma-*`, and
`.agents/skills/prisma-*` paths to also treat `.windsurf/skills/prisma-*` under
`process.cwd()` as installed, and keep the `already-installed` acknowledgement
behavior unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 8160c91e-8ee7-4c94-b104-ad1ef521c66b
📒 Files selected for processing (7)
projects/agent-native/reviews/code-review.mdprojects/agent-native/slices/generate-skill-offer/briefs/d1-r1.mdprojects/agent-native/slices/generate-skill-offer/briefs/d2-r1.mdprojects/agent-native/slices/generate-skill-offer/briefs/d3-r1.mdprojects/agent-native/slices/generate-skill-offer/plan.mdprojects/agent-native/slices/generate-skill-offer/spec.mdprojects/agent-native/trace.jsonl
All three S2 dispatches satisfied; scoreboard 5 PASS + 1 accepted deferral. Live pty evidence in the slice verification record. One session-limit stall (D15) retried cleanly.
… satisfied The MCP probe confirmed the checkpoint's consent text reaches clients intact (no runCommand fix needed); three-case pin test landed. D2 (description) dispatched.
Probe confirmed consent text survives the MCP transport; three-case pin + description contract landed. Scoreboard: 7 PASS, 1 accepted deferral, findings log empty across all three slices.
…s PR open Session totals: S1/S2/S3 at DoD (PRs 29689, 29690 stacked, 29691); S4 Half A delivered (prisma-engines#5836), Half B paused at the wasm-publish boundary. Scoreboard 8 PASS, 1 accepted deferral, 1 deferred-by-design; findings log empty across 9 dispatches and 10 review rounds. Decisions D1-D15; one retro landed.
The mongodb-upgrade-skill slice (adopted work TML-2973) closed the gap the operator surfaced: probe verdict recorded (Next MongoDB = present but partial, POC status), skill authored stay-on-v6-first with cited migrate-now branch, PR open on prisma/skills. Scoreboard 9 PASS, findings log still empty.
Windsurf layout carried into the S1 plan D3 outcome and the S2 spec's already-installed markers; tagging-ask wording aligned with the D14 accepted deferral; markdown language tag in the 001 task doc. Decision D16 records the round incl. two declined brief-rewrite suggestions (issued briefs are hash-pinned in the trace).
…dressed Nine comments triaged: 7 fixed (3 code commits across the slice branches, 4 doc fixes), 2 declined with replies (issued briefs are hash-pinned trace records). Reviewer verdict SATISFIED; findings log still empty. Decision D16.
…dressed EA reframe per operator ground truth (spec amendment recorded, D17); skill revised in 57574e3 (encourage-migration lead, agent self-checks, internal paths removed, driver access affirmed); engines suggestion applied in 74156ebdc16. All ten comment threads replied. Linear ticket for the transactions-merge skill refresh pending connector re-auth.
The hand-authored files under projects/agent-native/ never went through prettier and failed the Lint job on this branch. Issued dispatch briefs are exempted via .prettierignore instead of being reformatted: their byte-level sha256 hashes are recorded in the trace journal (brief-issued events), so formatting must not rewrite them.
aqrln
pushed a commit
that referenced
this pull request
Jul 9, 2026
`prisma init` now installs the [prisma/skills](https://github.com/prisma/skills) catalog into freshly scaffolded projects, so AI agents working in them start with current, version-relevant Prisma knowledge instead of stale training data. First slice (S1) of the Agent-Native Prisma ORM project — spec and plan in `docs/plans/agent-native/` and `projects/agent-native/` (#29688). ## Changes - **Skill-install runner** (`packages/cli/src/init/skill-install.ts`): executes `<runner> skills@1.5.14 add prisma/skills --agent cursor claude-code codex windsurf --skill '*' --copy -y` via execa, streaming output. The runner adapts to the invoking package manager (`npx --yes` / `pnpm dlx` / `yarn dlx` / `bunx`), detected from `npm_config_user_agent`, then the Bun runtime, then a lockfile sniff, defaulting to npm. Yarn 1 routes through npx — classic yarn has no `dlx`. `installSkills` never throws: any failure resolves to `{ ok: false, manualCommand }`. - **Init wiring** (`packages/cli/src/Init.ts`): the install runs after file scaffolding (both default and Prisma Postgres new-project flows); `--no-skills` opts out (arg spec + help). Success appends `.claude/skills/`, `.windsurf/skills/`, `.agents/skills/`, `skills-lock.json` to the init summary; failure prints a warning with the copy-pasteable manual command and init still exits 0. The PPG existing-project path (which scaffolds nothing) skips the install. - **Tests**: 43 passing in `packages/cli` — 17 runner unit tests (command assembly per package manager, detection fallbacks, failure shapes; injected exec, no network, no module mocks) and 26 Init tests including 4 new integration cases (default invokes the runner, `--no-skills` skips, failure is non-fatal, help lists the flag). Snapshot updates are exactly the new summary lines. ## Why - **Default-on with a clean opt-out** implements the project spec's distribution goal (zero-configuration agent readiness), following the prisma-next precedent — with two deliberate deviations: the `skills` CLI version is **pinned** (supply-chain hygiene; bumped via Renovate) and install failure is **non-fatal** (the stable CLI must never fail scaffolding over an auxiliary network step). - **`--copy` instead of the default symlink layout**: skills@1.5.14 with multiple `--agent` values writes only the universal `.agents/skills/` tree and silently skips the per-agent symlinks its own plan output promises (verified empirically; upstream bug report prepared). `--copy` materializes real `.claude/skills/` and `.windsurf/skills/` copies so Claude Code and Windsurf find skills where they actually look. - **Default-branch install for now**: prisma/skills has no release tags yet; a prepared ask requests per-ORM-minor tags so the install can pin `prisma/skills#v<minor>` in a follow-up. ## Verification (live runs, built CLI, clean env) - **Default `prisma init`**: exit 0; all 8 catalog skills present in each of `.claude/skills/`, `.windsurf/skills/`, `.agents/skills/` (24 `SKILL.md` files, zero symlinks); `skills-lock.json` written; summary matches disk. - **Forced failure** (unreachable registry): exit 0; scaffolding intact; warning printed with the manual command. - **`--no-skills`**: exit 0; no agent artifacts. Full evidence and the two prepared external filings (tagging ask for prisma/skills; symlink bug for vercel-labs/skills) live in `projects/agent-native/slices/init-skill-install/verification.md` on the project branch (#29688). **Linear:** [TML-2968](https://linear.app/prisma-company/issue/TML-2968/s1-install-prisma-skills-during-prisma-init)
aqrln
pushed a commit
that referenced
this pull request
Jul 22, 2026
> **Stacked PR** — based on #29689 (S1, the skill-install runner); will be retargeted to `main` once #29689 merges. The diff here is only S2's two commits. Existing projects (which never ran the new `prisma init`) get exactly one polite, interactive, time-limited offer to install the [prisma/skills](https://github.com/prisma/skills) catalog, shown after a successful `prisma generate`. Second slice (S2) of the Agent-Native Prisma ORM project (#29688). ## Changes - **Offer module** (`packages/cli/src/utils/skills/skills-offer.ts`): `handleSkillsOffer()` runs the full NPS-style gate chain — prior acknowledgement, already-installed detection, interactive TTY, Deno guard, CI, git hook, npm lifecycle hook, container, and "first Prisma command ≥ 1 day ago" — then asks one yes/no question with a 30-second timeout defaulting to No. Every outcome (`accepted` / `declined` / `timeout` / `already-installed`) persists `skills-offer.json` in the OS config dir, so the offer fires **once ever per machine** (unlike the NPS survey's once-per-timeframe). Accepting runs S1's pinned skill-install runner; failure prints the manual command, non-fatally. The whole body never throws — an offer failure can never fail `generate`. - **Generate wiring** (`packages/cli/src/Generate.ts`): the offer runs in the existing `!hideHints` non-watch success block, before the NPS survey; if the offer prompted, the survey is skipped for that run — at most one prompt per generate. Injectable handler mirroring the existing `surveyHandler` seam. - **Shared helper** (`packages/cli/src/utils/prompt-timeout.ts`): the `timeout()` racer extracted verbatim from `nps/survey.ts`; both prompts now share it. - **Telemetry**: a single `skills_offer_resolved` `{ outcome, cliVersion }` event through the existing PostHog capture path, only when a prompt was actually shown. - **Tests**: 27 unit tests for the module (every gate short-circuit, input variants, fake-timer timeout, four failure-isolation cases) + 4 Generate-level tests (ordering, mutual exclusion both ways, `--no-hints` and watch suppression). Injection over module mocking throughout. ## Why - **Once-ever, not once-per-timeframe**: a declined offer should never nag again; `prisma init` (S1) and docs remain the discovery paths. - **Acknowledgement only after a prompt resolves**: gated-out runs (CI, non-TTY) write nothing, so a developer whose first runs are in CI still gets the offer later on a real TTY. - **Ordering inside the resolution path** (acknowledge → install → telemetry) makes once-ever survive a crash mid-install and keeps an offline telemetry endpoint from robbing an accepting user of the install. - **Mutual exclusion with NPS** keeps the post-generate moment to a single question, ever. ## Verification (live pty runs, built CLI, isolated config dirs) - First interactive run: offer shown; `n` persists `outcome: "declined"`; second run silent. - Accept run: skills land via the S1 runner (24 SKILL.md across `.claude`/`.windsurf`/`.agents` + `skills-lock.json`); `outcome: "accepted"`. - Non-TTY run: no prompt, no acknowledgement written, generate output normal. - In prompted runs the offer was the only prompt (NPS skipped; mechanism also pinned by unit tests). Full captures: `projects/agent-native/slices/generate-skill-offer/verification.md` on the project branch (#29688). **Linear:** [TML-2971](https://linear.app/prisma-company/issue/TML-2971/s2-one-time-skill-offer-on-prisma-generate)
lh0x00
pushed a commit
to lh0x00/prisma
that referenced
this pull request
Aug 9, 2026
…isma#29688) ## Overview Planning-only PR: no product code changes. It adds the spec and task plan for making Prisma ORM **agent-native** — AI agents operating Prisma succeed by default: current knowledge installed where agents look, destructive actions gated behind user consent, sharp API edges documented with engine-verified semantics, and machine-friendly CLI surfaces. ## Contents **`docs/plans/agent-native/`** — detailed task drafts, following the existing `docs/plans/` convention: - `000` index: vision, verified current state, goals/non-goals, task table, execution phases, risks, future ideas - `001` skill install during `prisma init` (prisma-next precedent; deviations: non-fatal failure, pinned `skills` CLI version) - `002` one-time interactive skill offer on `prisma generate` (reuses the NPS survey gating, timeout, and persistence machinery) - `003` AI safety checkpoint: land prisma#29684 + `prisma mcp` interplay audit - `004`–`007`, `009`–`010` skill content for [prisma/skills](https://github.com/prisma/skills): connection/URL routing, generate-after-schema-change (+ Claude Code plugin), troubleshooting suite, API pitfalls with engine-test citations, performance playbook, ORM vs platform CLI disambiguation - `008` move `typedSql` out of hidden preview (prisma-engines + schema Wasm bump) - `011` `prisma-mongodb-upgrade` skill: v6 → Prisma Next migration path (v7 ships no MongoDB connector) **`projects/agent-native/`** — the drive project workspace (spec, plan, design notes, trace journal). The plan composes four slices: init skill install → generate skill offer (stack), plus MCP safety audit and typedSql unhide (parallel). The prisma/skills content executes as a sibling project in that repo. **`AGENTS.md`** — records the NPS survey infrastructure, the `prisma mcp` command, and the `docs/plans/` convention for future agent sessions. ## Tracking - Linear project: [Agent-Native Prisma ORM](https://linear.app/prisma-company/project/agent-native-prisma-orm-da6125fbcbac) (anchor TML-2967; slices TML-2968–2971; adopted work TML-2972, TML-2973) - Related: prisma#29684 (AI safety marker refresh, in review — gates the S3 slice) ## Notes for reviewers - Behavioral claims in the API-pitfalls task (`AND: []`/`OR: []` semantics, vacuous `every`, silently dropped `undefined` in `deleteMany`, `typedSql` hidden status) were verified against the query-engine test suite and the PSL/serializer sources; citations are in the task docs. - Open design questions (init default-on vs detection-gated, plugin placement, offer acknowledgement scope) are recorded with working positions in `projects/agent-native/spec.md` § Open Questions.
lh0x00
pushed a commit
to lh0x00/prisma
that referenced
this pull request
Aug 9, 2026
`prisma init` now installs the [prisma/skills](https://github.com/prisma/skills) catalog into freshly scaffolded projects, so AI agents working in them start with current, version-relevant Prisma knowledge instead of stale training data. First slice (S1) of the Agent-Native Prisma ORM project — spec and plan in `docs/plans/agent-native/` and `projects/agent-native/` (prisma#29688). ## Changes - **Skill-install runner** (`packages/cli/src/init/skill-install.ts`): executes `<runner> skills@1.5.14 add prisma/skills --agent cursor claude-code codex windsurf --skill '*' --copy -y` via execa, streaming output. The runner adapts to the invoking package manager (`npx --yes` / `pnpm dlx` / `yarn dlx` / `bunx`), detected from `npm_config_user_agent`, then the Bun runtime, then a lockfile sniff, defaulting to npm. Yarn 1 routes through npx — classic yarn has no `dlx`. `installSkills` never throws: any failure resolves to `{ ok: false, manualCommand }`. - **Init wiring** (`packages/cli/src/Init.ts`): the install runs after file scaffolding (both default and Prisma Postgres new-project flows); `--no-skills` opts out (arg spec + help). Success appends `.claude/skills/`, `.windsurf/skills/`, `.agents/skills/`, `skills-lock.json` to the init summary; failure prints a warning with the copy-pasteable manual command and init still exits 0. The PPG existing-project path (which scaffolds nothing) skips the install. - **Tests**: 43 passing in `packages/cli` — 17 runner unit tests (command assembly per package manager, detection fallbacks, failure shapes; injected exec, no network, no module mocks) and 26 Init tests including 4 new integration cases (default invokes the runner, `--no-skills` skips, failure is non-fatal, help lists the flag). Snapshot updates are exactly the new summary lines. ## Why - **Default-on with a clean opt-out** implements the project spec's distribution goal (zero-configuration agent readiness), following the prisma-next precedent — with two deliberate deviations: the `skills` CLI version is **pinned** (supply-chain hygiene; bumped via Renovate) and install failure is **non-fatal** (the stable CLI must never fail scaffolding over an auxiliary network step). - **`--copy` instead of the default symlink layout**: skills@1.5.14 with multiple `--agent` values writes only the universal `.agents/skills/` tree and silently skips the per-agent symlinks its own plan output promises (verified empirically; upstream bug report prepared). `--copy` materializes real `.claude/skills/` and `.windsurf/skills/` copies so Claude Code and Windsurf find skills where they actually look. - **Default-branch install for now**: prisma/skills has no release tags yet; a prepared ask requests per-ORM-minor tags so the install can pin `prisma/skills#v<minor>` in a follow-up. ## Verification (live runs, built CLI, clean env) - **Default `prisma init`**: exit 0; all 8 catalog skills present in each of `.claude/skills/`, `.windsurf/skills/`, `.agents/skills/` (24 `SKILL.md` files, zero symlinks); `skills-lock.json` written; summary matches disk. - **Forced failure** (unreachable registry): exit 0; scaffolding intact; warning printed with the manual command. - **`--no-skills`**: exit 0; no agent artifacts. Full evidence and the two prepared external filings (tagging ask for prisma/skills; symlink bug for vercel-labs/skills) live in `projects/agent-native/slices/init-skill-install/verification.md` on the project branch (prisma#29688). **Linear:** [TML-2968](https://linear.app/prisma-company/issue/TML-2968/s1-install-prisma-skills-during-prisma-init)
lh0x00
pushed a commit
to lh0x00/prisma
that referenced
this pull request
Aug 9, 2026
…#29690) > **Stacked PR** — based on prisma#29689 (S1, the skill-install runner); will be retargeted to `main` once prisma#29689 merges. The diff here is only S2's two commits. Existing projects (which never ran the new `prisma init`) get exactly one polite, interactive, time-limited offer to install the [prisma/skills](https://github.com/prisma/skills) catalog, shown after a successful `prisma generate`. Second slice (S2) of the Agent-Native Prisma ORM project (prisma#29688). ## Changes - **Offer module** (`packages/cli/src/utils/skills/skills-offer.ts`): `handleSkillsOffer()` runs the full NPS-style gate chain — prior acknowledgement, already-installed detection, interactive TTY, Deno guard, CI, git hook, npm lifecycle hook, container, and "first Prisma command ≥ 1 day ago" — then asks one yes/no question with a 30-second timeout defaulting to No. Every outcome (`accepted` / `declined` / `timeout` / `already-installed`) persists `skills-offer.json` in the OS config dir, so the offer fires **once ever per machine** (unlike the NPS survey's once-per-timeframe). Accepting runs S1's pinned skill-install runner; failure prints the manual command, non-fatally. The whole body never throws — an offer failure can never fail `generate`. - **Generate wiring** (`packages/cli/src/Generate.ts`): the offer runs in the existing `!hideHints` non-watch success block, before the NPS survey; if the offer prompted, the survey is skipped for that run — at most one prompt per generate. Injectable handler mirroring the existing `surveyHandler` seam. - **Shared helper** (`packages/cli/src/utils/prompt-timeout.ts`): the `timeout()` racer extracted verbatim from `nps/survey.ts`; both prompts now share it. - **Telemetry**: a single `skills_offer_resolved` `{ outcome, cliVersion }` event through the existing PostHog capture path, only when a prompt was actually shown. - **Tests**: 27 unit tests for the module (every gate short-circuit, input variants, fake-timer timeout, four failure-isolation cases) + 4 Generate-level tests (ordering, mutual exclusion both ways, `--no-hints` and watch suppression). Injection over module mocking throughout. ## Why - **Once-ever, not once-per-timeframe**: a declined offer should never nag again; `prisma init` (S1) and docs remain the discovery paths. - **Acknowledgement only after a prompt resolves**: gated-out runs (CI, non-TTY) write nothing, so a developer whose first runs are in CI still gets the offer later on a real TTY. - **Ordering inside the resolution path** (acknowledge → install → telemetry) makes once-ever survive a crash mid-install and keeps an offline telemetry endpoint from robbing an accepting user of the install. - **Mutual exclusion with NPS** keeps the post-generate moment to a single question, ever. ## Verification (live pty runs, built CLI, isolated config dirs) - First interactive run: offer shown; `n` persists `outcome: "declined"`; second run silent. - Accept run: skills land via the S1 runner (24 SKILL.md across `.claude`/`.windsurf`/`.agents` + `skills-lock.json`); `outcome: "accepted"`. - Non-TTY run: no prompt, no acknowledgement written, generate output normal. - In prompted runs the offer was the only prompt (NPS skipped; mechanism also pinned by unit tests). Full captures: `projects/agent-native/slices/generate-skill-offer/verification.md` on the project branch (prisma#29688). **Linear:** [TML-2971](https://linear.app/prisma-company/issue/TML-2971/s2-one-time-skill-offer-on-prisma-generate)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
Planning-only PR: no product code changes. It adds the spec and task plan for making Prisma ORM agent-native — AI agents operating Prisma succeed by default: current knowledge installed where agents look, destructive actions gated behind user consent, sharp API edges documented with engine-verified semantics, and machine-friendly CLI surfaces.
Contents
docs/plans/agent-native/— detailed task drafts, following the existingdocs/plans/convention:000index: vision, verified current state, goals/non-goals, task table, execution phases, risks, future ideas001skill install duringprisma init(prisma-next precedent; deviations: non-fatal failure, pinnedskillsCLI version)002one-time interactive skill offer onprisma generate(reuses the NPS survey gating, timeout, and persistence machinery)003AI safety checkpoint: land chore(migrate): modernize AI agent detection in the safety checkpoint #29684 +prisma mcpinterplay audit004–007,009–010skill content for prisma/skills: connection/URL routing, generate-after-schema-change (+ Claude Code plugin), troubleshooting suite, API pitfalls with engine-test citations, performance playbook, ORM vs platform CLI disambiguation008movetypedSqlout of hidden preview (prisma-engines + schema Wasm bump)011prisma-mongodb-upgradeskill: v6 → Prisma Next migration path (v7 ships no MongoDB connector)projects/agent-native/— the drive project workspace (spec, plan, design notes, trace journal). The plan composes four slices: init skill install → generate skill offer (stack), plus MCP safety audit and typedSql unhide (parallel). The prisma/skills content executes as a sibling project in that repo.AGENTS.md— records the NPS survey infrastructure, theprisma mcpcommand, and thedocs/plans/convention for future agent sessions.Tracking
Notes for reviewers
AND: []/OR: []semantics, vacuousevery, silently droppedundefinedindeleteMany,typedSqlhidden status) were verified against the query-engine test suite and the PSL/serializer sources; citations are in the task docs.projects/agent-native/spec.md§ Open Questions.