Build and ship
Use Build and ship for the decisions that shape normal app work. ZCP MCP gives the agent Zerops project state, platform guidance, project-scoped operations, deploy evidence, and recovery rules. You still decide what should be built, where it should run, how strict the acceptance criteria are, and what happens after proof.
A prompt can be that short when the outcome is enough. Add detail when it changes behavior, architecture, stack, runtime layout, acceptance criteria, credentials, delivery, packaging, or the production release.
The expected output is a verified running change, not only generated files. The agent should prove the request against a real runtime, real managed services when used, and the logs, events, and checks that explain what happened.
The decisions
Build a task board...1. Runtime layout
Choose where app work should land.
- Use existing services
- Create missing services
- Pick dev, stage, or linked target
2. Development
The agent gets current state, Zerops knowledge, deploy evidence, and your product instructions.
3. After proof
Decide what happens to verified work.
- Direct deploy, git, or CI
- Optional package bundle
- Production release
You do not run these steps by hand. They are the parts where your intent changes what the agent should do. If you do not specify a choice, the agent should infer from current project state and ask only when the decision changes cost, credentials, runtime layout, delivery, production risk, or destructive behavior.
1. Choose the runtime layout
When the app runtime and dependencies are unclear, the workflow prepares the layout before feature work starts. It reads current state, uses existing services when they fit, creates missing runtimes or managed services when needed, and stops when the agent knows where app code belongs.
The main user-facing choice is runtime layout. Let the agent infer it from the project, or name it in the prompt when it matters.
| Runtime layout | Use when | What to tell the agent |
|---|---|---|
| Dev | You want one mutable runtime for fast iteration, experiments, or early app work. | Build a small Node.js API on dev. |
| Dev + stage | You want a development runtime plus a separate runtime for review or release rehearsal. | Build a Node.js API with PostgreSQL on dev+stage. |
| Stage / linked target | You work from local files or a single target runtime and want the workflow to use that target. | Use appstage as the deploy target for this local app. |
The layout is about app runtimes, not where the zcp binary runs. Remote setup can use any of these layouts from the zcp@1 workspace. Local setup usually works from local files into a linked stage or app runtime.
Managed services such as PostgreSQL, Valkey, queues, search, storage, or mail are dependencies. The agent gets their state and wiring patterns, but app code deploys to runtime services.
2. Development
Development is still a normal coding conversation with the agent. You describe the product behavior, stack constraints, acceptance criteria, and anything the agent must not guess.
MCP adds the Zerops side of that conversation: current project state, platform knowledge, project-scoped operations, deploy/log evidence, verification checks, recovery rules, and saved work state. Because of that, you usually do not paste service inventory, env wiring, deploy logs, or a "deploy and verify" checklist into the prompt.
The useful things to name are:
- the behavior you want and how it should be verified,
- stack, framework, managed-service, or runtime target preferences,
- whether the agent should inspect or continue existing work first,
- approval boundaries for cost, credentials, data, production, or destructive actions.
Expect the agent to ask when one of those choices is missing. Otherwise, it should use project context while it works and finish with proof or a blocker.
3. Choose delivery after proof
Delivery preference is how app work closes after there is a verified result. Include it in the original prompt or set it later.
The first functional deploy is still direct so the agent can prove the app runs. Delivery preference decides what happens after that proof and how later sessions should finish similar work.
| Delivery preference | What it means | What to tell the agent |
|---|---|---|
| Keep direct deploy | The agent keeps deploying directly to the target runtime for fast dev/stage iteration. | Keep direct deploy for now. |
| Push to git | The agent commits and pushes working changes to the configured repository. | When the app works, push changes to git@github.com:my-org/task-board.git. |
| CI / handoff | A repository integration, GitHub Actions workflow, release process, or human owns the next deploy. | Set up GitHub Actions delivery for future deploys after the app works. |
The workflow records the delivery choice so later work can follow it. Git credentials, CI secrets, and production credentials are separate from ZCP_API_KEY; see Tokens and credentials.
4. Package a verified runtime
After a runtime is verified, you can ask the agent to prepare it as a re-importable Zerops project bundle. Use this when the app should become a reusable starter, customer handoff, demo project, or clean staging project.
The prompt can be one sentence:
The export workflow prepares zerops-project-import.yaml and zerops.yaml in the same git repo as the app. The import file contains one runtime with buildFromGit: pointing back to that repo, plus managed services needed for Zerops env references to resolve when the bundle is imported into a fresh project.
The agent may still ask which runtime to package, which half of a dev+stage pair to use, how to classify project env vars, or how to configure git push. Once pushed, the target project can import the bundle from the dashboard or with zcli project project-import zerops-project-import.yaml.
Packaging is not the next deploy of the same app. For the next app change, keep using the normal build/deploy/verify loop. Use packaging when the output you want is a git-backed import bundle; see Package a running service.
5. Prepare the production release
The production release is where authority changes. The agent prepares verified work and release evidence; production execution belongs to Zerops project settings, CI, release tooling, or a deliberate human action with production credentials.
The useful split is:
| Job | How often | What happens |
|---|---|---|
| Production infrastructure | Once per production project | Export the verified project as YAML in the GUI, edit it for production, then import it as a new project. |
| Production deploy trigger | Once per production runtime | Connect the production runtime to git, usually with a tag trigger. |
| Production release | Every release | Verify in dev/stage, push source to git, then trigger production through your tag or release process. |
Production should be a separate Zerops project without a zcp service. Production credentials are not ZCP_API_KEY; keep them in CI or release tooling. For the full release guide, see Promote to production.
What the final answer should contain
For a completed app task, the agent should report:
- the runtime service it changed,
- the deploy or verification target,
- the URL, endpoint, UI state, job result, or stored data that proves the requested behavior,
- managed services, env vars, or delivery settings it touched,
- the delivery preference, packaging output, or production release state that now applies.
If the task is incomplete, the final answer should name the blocker, the evidence read, what was tried, and the decision or credential needed from you.