@nullplatform/mcp 0.1.5 → 0.1.7

package/skills/starting-a-new-app/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: starting-a-new-app
+description: Use when standing up something NEW on nullplatform — a new application (or a small set, e.g. a frontend and its API), choosing where it lives, wiring its data dependencies, and getting it to a first running deploy before any features are built. The greenfield counterpart to working-from-a-ticket.
+---
+
+# Starting a new app on nullplatform
+
+nullplatform owns the *platform* half — where the app lives, how it ships, what it depends on.
+The code is your own craft. This playbook carries a new thing from a request to its first running
+deploy with its dependencies wired, then hands the feature-building back to you. Do it in order:
+each step de-risks the next. Standing up the skeleton and *then* coding beats coding against a
+platform you haven't proven yet.
+
+## 1. Place it before you create it
+
+`application_create` opens a pre-filled form — but *where* it goes is a real decision, not a
+default. Read the request for the home it implies (a demo for a banking client in Argentina is not
+the same namespace as a throwaway): list the namespaces the form offers and pick the account +
+namespace that fits, and confirm that choice for anything that isn't obviously disposable. New repo
+vs. importing an existing one is the other fork the form covers; it derives the repo URL for new ones.
+
+A request often implies **more than one app** (a frontend *and* its API). Create them one at a time
+in the same namespace, named so the pair reads as a set — there is no batch-create, and that's fine:
+two focused creates are clearer than one opaque one.
+
+## 2. Get it running before you build on it
+
+Deploy the boilerplate to a real scope *first*, so the next step is "add features to a running app,"
+not "debug the platform and my code at once." Create the target environment with
+`managing-environments`, then ship the skeleton with `deploying-safely` (first-ever-deploy semantics
+live there). Real environments are usually **policy-gated** — a production scope or deploy may land
+in `creating_approval`; that's normal, surface it and don't fight it, keep moving on what isn't gated.
+
+## 3. Wire the data it needs
+
+A new product usually needs a dependency — a SQL database, a queue, a cache. `application_service_list`
+shows what's already attached and the catalog available; `application_service_create` provisions one
+and autolinks it. Provisioning creates **real cloud resources (cost-bearing)** and runs
+asynchronously, so it is **form-first**: call it to open the form, let the user fill the parameters
+and submit (the submit is the cost confirmation) — never pass `provision:true` unprompted. Target the
+link at the scope that needs the data. Don't call it "ready" until the service is active and linked.
+
+Once a service is linked, its connection details arrive **automatically as read-only parameters**
+(`DATABASE_URL`, host, credentials — secrets masked). Your code reads those env vars; you never
+hard-code them or re-create them by hand. New parameters only reach a running scope on the **next
+deploy**.
+
+## 4. Hand off to the build
+
+The platform's job is done when the app exists, runs, and its dependencies are wired and surfaced as
+parameters. Writing the REST API, the UI, the schema or its codegen — that is your craft, not this
+playbook's job (same boundary as `working-from-a-ticket`). Build against the injected env vars, keep
+the work on a branch with the issue key (`tracing-a-change`), push so CI produces a build, and ship
+it with `deploying-safely`.
+
+## 5. Configure and redeploy
+
+App-level config the code expects — a page-size cap, feature flags — is a parameter, not a code
+constant: set it with `application_parameter_create` (`configuring-safely` for targeting at app vs.
+scope vs. dimension). Remember values apply on the **next** deploy, so redeploy to pick them up.
+
+## Don'ts
+
+- Don't drop a new app in the default namespace without checking it fits the request.
+- Don't write feature code before the boilerplate has a running deploy — prove the platform first.
+- Don't re-create or hard-code connection details a service link already injects — read them as
+  parameters (they're `read_only`).
+- Don't treat provisioning as instant — it's async and costs money; confirm before, and don't mark
+  data "ready" until the service is active, linked, and a redeploy has surfaced its params.
+- Don't block the whole product on one approval — production gates are routine; surface them and
+  keep moving on everything that isn't gated.