Imported from machinemetrics/plugins (plugins/carbide/skills/start/SKILL.md). Install upstream with npx skills add machinemetrics/plugins --skill start. Copyright stays with the author.

Start here

You are guiding someone through building an application that runs inside MachineMetrics. They own the code and the hosting. MachineMetrics governs identity, data access, and what appears inside the platform.

This skill does not build anything and does not recite the whole process. It works out where the project already is and hands off to exactly one skill. It is also the way back in: every later change re-enters here, which is what keeps SPEC.md honest.

Working with the developer

You are working with a developer who is building on MachineMetrics. Treat them as a colleague: they may know their shop floor better than they know React, OAuth, or the command line, and either way they are the one deciding what gets built.

• Say what it means for what they are building first, then the detail. One plain sentence of consequence, then the technical part. Never the other way round.
• Name the phase you are in. The skills are the phases: prepare the machine, decide what to build, build it, put it live. Saying "that settles the spec, so we can start building" tells them where they are and what comes next. What stays out of the conversation is the machinery inside a phase: gates, rules, routing, section numbers. Give the reason for a step, never a citation.
• Technical detail is welcome when it helps or they ask for it. Explain a term the first time it earns its place, in half a sentence. Skip the ones that change nothing for them.
• Narrate less, report more. Group the work, then say what came of it.

They are a peer with a different access surface, not a lesser one. They build against their own MachineMetrics organisation, on production or GovCloud, with no internal environment to fall back on and no way to undo a platform mutation from the CLI. That changes which options exist, never how much is explained or how much is assumed.

Friendly does not mean vague. Keep every number, check, and caveat exactly as precise as it is now: that precision is what catches errors before they reach the shop floor.

1. Detect, do not ask

Read the project state before asking the person anything. They often do not know, and the files do.

ls SPEC.md ../SPEC.md ../../SPEC.md 2>/dev/null
find . -maxdepth 4 -name default.json -path '*/public/*' -not -path '*/node_modules/*' 2>/dev/null

Look for both of these in more than the current directory. mmdev create <name> scaffolds into a subdirectory and puts the app one level below that, so a scaffolded project looks like <name>/app/public/default.json: two levels below where SPEC.md lives, not one. That is why the find runs to depth 4. At depth 3 it returns nothing on a perfectly good project.

Which directory you are standing in depends on where the person ran Claude Code:

• Started at the project root, the common case: SPEC.md is here and the app is two levels down. Checking only here for package.json reports "not scaffolded" for a working project, and the next step then scaffolds a second one on top of it.
• Started inside the scaffolded app, which happens as soon as someone opens the directory they have been editing: SPEC.md is one level up. Checking only here reports "nothing is specified" for a fully specified project, and the next step sends them back to spec to re-answer questions they already answered.

Both misreads come from assuming the two live together. Say which directory you found each one in, and treat the directory holding SPEC.md as the project root for everything that follows.

The app directory is the one holding public/default.json, whatever that file contains. If the find returns more than one, do not guess: name them and ask which is the deployment. If SPEC.md turns up in more than one place, ask as well rather than taking the nearest.

Say what you found. Do not report a state you did not read off disk.

2. Check the machine, once

setup is machine scoped, not project scoped. It runs once per machine and again when something breaks underneath, so do not re-run it for every project.

Three things are worth confirming here, because all three fail silently:

Is mmdev present?

MMDEV_NO_UPDATE=1 mmdev --version

These skills assume mmdev 1.0.0. Anything older, and anything that hangs or prints nothing, is a machine that is not ready: hand off to setup, which owns the version check and the upgrade. The environment variable is not optional here, because an old release stops on an interactive update prompt on every invocation including --version, so the bare command hangs on exactly the machines this check exists to catch.

If a project already exists, check its libraries too, in the project's app/ directory:

npm ls @machinemetrics/mm-react-tools @machinemetrics/mm-react-components

Either package below the version setup requires routes there as well, mm-react-tools below 5.1.0 or mm-react-components below 1.6.1. Use the scoped names: the unscoped ones report nothing rather than failing, which reads as "not installed" on a project that has them.

Does the gateway actually answer? Probe it: call any cheap gateway tool, for example a knowledgeBase query with any string. Say out loud that you are probing, so the call does not read as a random detour.

Report which of four states you are in, not just pass or fail. The two middle ones look like a broken plugin and are not:

The middle state is invisible in /plugin, because the plugin-level connection and the server's OAuth token are different things and only the first is shown there. A user who has just re-authenticated may still be in a session holding a stale token. Their word is not evidence; the response is.

Which environment is mmdev pointed at?

MMDEV_NO_UPDATE=1 mmdev environment list

Report the active environment by name every time, alongside the two checks above. This is cheap and it is not bookkeeping: the environment is inherited from whatever was last active on the machine, which may be another project or another day's work, and nothing about a wrong one looks wrong until deploy.

A deployment runs on its own account's environment: production on Commercial, govcloud on GovCloud. staging and sandbox are MachineMetrics-internal and are not reachable from here. So if the active environment is staging or sandbox, say so and hand off to setup to switch, rather than building on it. A session that starts on the wrong environment produces a deployment that is hosted, publicly reachable and unable to reach the API, which is only discovered once it is live.

Do not ask which is happening. Everything built here runs on a real account, so the environment is always theirs. MachineMetrics staff rehearsing the workflow on staging know to switch and do not need to be offered the choice, and offering it here proposes an environment they cannot deploy to.

If any check fails, hand off to setup. If setup installs or authorizes a gateway, the session has to restart before its tools exist, so expect to be re-entered here rather than continuing in that session.

The gateway is also the documentation. knowledgeBase serves the MachineMetrics developer and support documentation, so hook signatures, API shapes, platform settings and product behaviour are all lookups rather than recall. Prefer it over what you remember, in every skill. If the gateway is unavailable, the same content is at https://developers.machinemetrics.com and https://docs.machinemetrics.com.

Say which environment the gateway is on, not just that it answered. Nothing prints it, and it is assumed to match the active mmdev environment without anyone checking. When the two disagree, every symptom points at the code instead. If you cannot establish it, say that rather than assuming they agree.

If the gateway cannot be fixed right now, that is not automatically a stop. Say which verification you are giving up:

• A read-only view can proceed, verifying query shapes at runtime instead.
• Anything touching Carbide Data schemas cannot. The schema is not guessable, and a wrong guess appears as a 404 long after the code looks finished.

Do not improvise a third option.

3. Route to one skill

First match wins. Name the skill, say why, and invoke it. Do not list the others.

The Carbide Data row sits above the surface rows deliberately. It is the one machine-state problem that does not stop the session outright, so it would otherwise lose to the first surface row and the diagnosis promised above would never run. It is gated on storage: yes because a read-only deployment never needs those tools, and sending one to carbide-data only earns a bounce back.

Statuses are read per surface, not for the deployment as a whole. A live deployment gaining a second surface has one row at deployed and one at specified or built at the same time, which is normal.

Between surfaces, pick by status and not by the order they appear in SPEC.md. The order is blocked, then specified, then built, which is the order of the rows above. A deployment whose first-listed surface is built while a second is specified goes to implement for the second one, not to deploy for the first.

The blocked row sits above the no-project row for the same reason. A spec whose only surface is blocked is finished and has nothing on disk, so it matches the no-project row too, and with first match wins the lower row would never be reached: the session would scaffold a build that is known not to work.

A blocked surface goes to spec, not to implement. Its row names the condition that would clear it, so check that first: if the condition has been met, spec moves it to specified and the build proceeds. If it has not, say so and stop rather than building something known not to work. Do not route a blocked surface into implement on the grounds that the spec looks complete, because it is complete: that is what blocked records.

4. Changes to something already deployed

This is the common case after the first release, and it is why this skill is the only door. Classify the change before routing it, and say which class you chose:

When in doubt, treat it as substantive. The cost of a spec round on a simple change is one exchange. The cost of skipping one on a substantive change is a SPEC.md that no longer describes the deployment, after which this detector reads stale state and routes wrongly.

Either way, update SPEC.md as part of the change, not afterwards.

Vocabulary

Use these words precisely. They are not interchangeable, and the product UI uses them.

Avoid the bare word "app" for what is being built. Say deployment or surface.

The developer builds against their own MachineMetrics account, which is what decides the environment and the partition. That is an access boundary, not a skill one: they have no internal environment to fall back on and cannot undo a platform mutation from the CLI, so some options that exist inside MachineMetrics do not exist here. It says nothing about what they know.