docs: consumer docs (README + guides) and one installable prisma-composer skill#90
Merged
Merged
Conversation
…-skill set Merge deploying-prisma-apps and testing-prisma-apps into a single self-contained skill, skills/prisma-composer, and add the missing authoring story: the mental model, contracts, the root module, builds, deploy config, databases (postgres/pnPostgres), reusable modules (cron/storage/streams), config params, secrets, and production pitfalls, plus an honest list of what Composer doesn't do yet. Fixes carried by the merge: - folder names now match frontmatter names (the runtimes key on frontmatter; the old folders said prisma-apps, the frontmatter said prisma-composers) - no link resolves outside the skill folder (the old testing skill linked ../../docs/design, which dangles once installed into another repo) - standaloneEntryPath corrected to standaloneServerPath (the export that actually ships) skills/README.md documents the install command and the authoring rules (verify every claim against packages/ while drafting; self-contained; concepts over procedures). Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io>
commit: |
Reorient the root README toward people building apps on Composer: what a service and a root module look like, the real examples/store topology in place of the aspirational diagram, a guides table, an examples table, and the agent-skill install. Design docs move to a "Design & internals" section for contributors. Everything described is shipped surface — unshipped design (stream connections, shared-Postgres contract slices, topology artifact queries) is no longer presented as current. Four guides, canonical for humans (the skill is the agent-condensed mirror; skills/README.md now says so): - getting-started.md — empty directory to a deployed two-service app - building-an-app.md — contracts, databases, Modules, shared modules, params, secrets, builds - testing.md — mockService / bootstrapService / the /fake pattern - deploying.md — stages, destroy, CI, production behavior All relative links checked against the tree; ADR links use the real filenames. Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io>
wmadden-electric
changed the title
Fresh-eyes rewrite of the README and all four guides, targeting a teammate who does not know Composer but wants to build or port an app onto Prisma Cloud, probably with Prisma Next. - README: opens with what the tool does and when it earns its keep (multi-piece apps), instead of category language; names the porting path. - getting-started: adds "Run it locally" (COMPOSER_* env vars — verified by actually running the cron example services locally and curling them) and a "Porting an existing app" section (Node/Bun service, Next.js app, multi-service); explains why Bun; says where the two deploy credentials come from. - building-an-app: reader-oriented opening (was a fragment); the Prisma Next database section now spells out the schema-change workflow (contract.prisma -> contract emit -> migration plan -> deploy applies); design-doc phrasing translated into reader benefit; ADR citations moved out of sentence flow into a closing "Digging deeper" list. - testing: says when to pick which seam; example is a complete runnable Vitest test with its imports. - deploying: explains deploy state and locking in plain terms; says where credentials come from; pitfalls phrased as what-you-hit -> what-to-do. All relative links and intra-guide anchors script-checked; vocabulary lint clean. Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io>
wmadden
approved these changes
Jul 16, 2026
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.
Two audiences, one surface: human guides (canonical) and an installable agent skill (the condensed mirror), plus a consumer-oriented root README linking both.
Human docs
examples/storetopology in place of the aspirational diagram, a guides table, an examples table, the agent-skill install. Design docs demoted to a "Design & internals" section. Shipped surface only — unshipped design (stream connections, shared-Postgres contract slices, topology artifact queries) is no longer presented as current.getting-started.md— empty directory to a deployed two-service appbuilding-an-app.md— contracts, databases (postgres/pnPostgres+ migrations), authoring reusable Modules, the shared cron/storage/streams modules, config params, secrets, buildstesting.md—mockService,bootstrapService, the/fakeentry-point patterndeploying.md— stages, destroy semantics, CI, production behavior (gotchas-derived)Agent skill
One self-contained skill,
skills/prisma-composer/, replaces thedeploying-prisma-apps+testing-prisma-appspair and adds the missing authoring story, sonpx skills add prisma/composer --skill prisma-composergives an agent the whole write-test-deploy workflow in one install.skills/README.mdrecords the install command, the authoring rules, and that the guides are canonical (a surface change lands in both).Shaping decisions (operator-settled): one skill, not a prisma-next-style ten-skill cluster — Composer's surface is small enough; guides/skill duplication is accepted because the audiences differ; describe only what ships.
Fixes riding along:
prisma-apps, the frontmatter saidprisma-composers— stale vocabulary)../../docs/design/..., which dangles once installed into another repo)standaloneEntryPathcorrected tostandaloneServerPath— the export that actually shipsVerification
@prisma/*import and symbol in the skill and guides checked against thepackages/9-public/*export maps and source barrels while drafting; CLI flags checked againstpackages/0-framework/3-tooling/cli/src/main.ts.npx skills add file://<repo> --skill prisma-composer -a claude-code -yinto a scratch project copies the skill to.claude/skills/prisma-composer/.lint:framework-vocabularyclean.🤖 Generated with Claude Code