@nullplatform/mcp 0.1.6 → 0.1.8

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

@@ -0,0 +1,84 @@
+---
+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
+
+An app lives in an **account + namespace** pair — `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) and pick the best-fitting
+pair from that context rather than the first on the list; pass `account` to disambiguate when a
+namespace name repeats across accounts, and `namespace`/`namespace_id` for the namespace. Confirm the
+choice for anything that isn't obviously disposable, and never drop it in the default namespace
+without checking it fits. New repo vs. importing an existing one is the other fork the form covers;
+it derives the repo URL for new ones.
+
+For a **new** repo the form also offers scaffolding **templates** — read them and pick the best fit
+for the stack (a React/SPA template for a UI, a Node/Express template for an API). If none fits
+cleanly, say so and offer the closest, or fall back to importing an existing repo — don't force a
+mismatched template. (Importing skips the template entirely: you bring a repo you already have.)
+
+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. Pull the repo, then build
+
+A new-from-template app is a fresh **remote** repo you've never cloned — so the move is forward, not
+backwards: **clone it into a folder and continue the work there**, rather than writing code first and
+retrofitting it onto the platform. (An imported app is already local; nothing to clone.) The create
+reply carries the repo URL; clone it, and if the request implied a pair (a frontend *and* its API),
+clone each into its own folder.
+
+Then the code is your own craft — writing the REST API, the UI, the schema or its codegen is 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.