---
name: zen-delivery
description: Deliver finished work the way professional teams do. Staging branch first, clear branch and commit names, small reviewed pull requests, and owner-approved promotion to production with version tags. Use when preparing a commit, a pull request, a merge or a release.
---
# Zen delivery

Get finished work safely from "it works on my machine" to "it works for users". This skill explains and prepares delivery. It does not perform it. Agent work ends in Review. Each commit, push, pull request, merge and promotion needs its own owner authorization.

## Why work goes through staging first

Work lands on a staging branch (called `canary` by default) first, where it is checked in a realistic setting. Only then does the owner promote it to production (`main`), so a mistake is found where it can not harm real users. Keeping the two apart is the single habit that stops most "I broke the live site" days.

## Environments

| Environment | Branch | Who moves work in | Purpose |
| --- | --- | --- | --- |
| Staging (canary) | `canary` | Merged from reviewed pull requests | Check the change where it is safe to break |
| Production | `main` | The owner, by promotion from canary | What real users run |

Never push straight to production. Never merge your own unreviewed pull request into production. Promotion is a deliberate owner decision, normally a reviewed pull request from `canary` into `main`.

## Authority

- Agent work finishes in Review.
- Committing, pushing, opening a pull request, merging and promoting are five separate decisions. An approval for one does not cover the others or a changed diff.
- Agents never mark a task Done. The owner does.

## Branch names

Use `<type>/<task-ref>-<slug>`:

- `type`: the same word as the commit type (feat, fix, docs, refactor and so on).
- `task-ref`: the human reference of the task, for example `CS-TSK-0012`.
- `slug`: two to five lowercase words joined by hyphens.

Zen lowercases the reference when it names a branch, so the branch Zen creates looks like `feat/cs-tsk-0012-csv-export`. Use the same lowercase form when you name a branch by hand.

Good: `feat/cs-tsk-0012-csv-export`, `fix/cs-tsk-0031-login-redirect`, `docs/cs-doc-0004-staging-guide`.

Bad: `new-stuff`, `my-branch`, `Feature/Export`, `fix/everything-this-week`.

## Commit messages (Conventional Commits)

Format: `type(scope)!: short summary`. Scope is optional and names the area of the change. The `!` marks a breaking change, which also needs a `BREAKING CHANGE:` line in the body that says what to do instead.

| Type | Use it for |
| --- | --- |
| feat | A new capability a user can see |
| fix | A correction to behaviour that was wrong |
| docs | Documentation only |
| style | Formatting only; no behaviour change |
| refactor | Restructuring with no behaviour change |
| perf | A measured speed or memory improvement |
| test | Adding or fixing tests only |
| build | Build tooling, dependencies, packaging |
| ci | Continuous integration configuration |
| chore | Housekeeping that fits no other type |
| revert | Undoing an earlier commit |

Rules: imperative mood ("add", not "added"), lower case after the colon, no full stop, the summary under about 72 characters. Put the why in the body when it is not obvious.

Good:
- `feat(export): add CSV download for tasks`
- `fix(auth): keep the session after a page refresh`
- `docs(zen): explain the staging branch`
- `feat(api)!: rename task.run to task.start` with the body line `BREAKING CHANGE: rename callers from task.run to task.start`

Bad:
- `stuff` (says nothing)
- `Fixed things` (no type, past tense, vague)
- `WIP` (never reaches a reviewer; use a draft pull request instead)
- `feat: export, login fix, new styles and docs` (several changes in one commit; split them)

## Pull requests

Title: the same format as a commit message, for example `feat(export): add CSV download for tasks`. The title is what appears in the release notes.

Body template:

```markdown
## Summary
One or two sentences: what changes for the user or the system.

## Why
The problem or goal, and the task it serves.

## Changes
- The main files or behaviours that changed (not every line).

## How it was tested
- Commands run and their actual results (for example: typecheck passed, tests passed, build passed).
- Anything not run, and why.

## Screenshots
Required for visible UI changes: before and after, desktop and mobile. Write "Not applicable" otherwise.

## Risk and rollback
What could go wrong, who would notice, and how to undo it (for example: revert this commit).

## Linked task
The task reference and its acceptance criteria.
```

Good pull requests are small and focused. One purpose each. If the title needs the word "and", the change probably belongs in two pull requests. A diff a reviewer can read in one sitting is the goal; it is a guide, not a rule.

Open pull requests as drafts until the checks have run and the work is ready for a reviewer. A draft tells everyone it is not yet safe to merge. The owner's `requireDraftPr` skill setting says whether drafts are the default for you to follow; the companion itself opens a ready pull request unless `draft` is set.

## Review before merge

Every pull request into `canary` or `main` gets a review before merge: a reviewer task, a human, or both, depending on its tier and whether security is involved. A review that is missing, incomplete or unclear is not an approval. The reviewer checks the actual diff against the acceptance criteria and reports findings with proof.

## Promotion to production

When the owner promotes canary to `main`:

1. Confirm canary has been checked where it runs and that its pull requests were reviewed.
2. Open a reviewed pull request from `canary` into `main`. Its body lists every change included.
3. Tag the release with a semantic version: `vMAJOR.MINOR.PATCH`. A fix increases PATCH, a new capability increases MINOR, a breaking change increases MAJOR.
4. Write release notes from the merged titles: New, Fixed, Breaking changes, and how to migrate. The `releaseNotes` setting controls whether notes are drafted.

## Checks before any delivery

Run the applicable project checks first (see [pre-checks](../zen-pre-checks/SKILL.md)). Then describe the exact operation and its target with [pre-push](../zen-pre-push/SKILL.md). Earlier results on a different diff are stale evidence.

## Skill settings

The owner's settings for this skill arrive in a "Skill settings" block. Honour them:

- `requireDraftPr` (default on): when on, every pull request is opened as a draft and is not marked ready until the checks have run and the owner asks for review. When off, the pull request may be opened ready for review, but review before merge still applies. The companion does not read this setting. Its `git.pr` operation opens a ready pull request unless `draft` is `true`, so pass `draft: true` yourself when this setting is on.
- `releaseNotes` (default on): when on, draft release notes at promotion. When off, skip them and say so in the report.

## Companion support

The companion provides owner-only Git operations: `git.preview`, `git.commit`, `git.push`, `git.merge` and `git.pr`. Agents do not call them; the owner does, from the task's delivery panel or with the owner connection.

- `git.pr` takes `{workspaceId, taskId?, title, body?, base?, draft?}`. The base defaults to the workspace's staging branch. The production branch is used only when it is named. If a pull request already exists for the task branch, the companion returns it. The title must follow Conventional Commits when the workspace uses them.
- Workspaces have delivery settings `{stagingBranch, productionBranch, commitConvention, branchNaming}`. The defaults are `canary`, `main`, Conventional Commits and named branches.
- `git.commit` refuses a message whose first line is not Conventional Commits and returns a suggested message in its error details.

Do not claim a commit, push or pull request was made unless the companion's result shows it. Until a live run has verified these operations, say so when reporting, and follow this guide by hand if the owner asks you to.

## Output

Use [the delivery packet](references/output.md). It names the branch, the target, the diff, the checks and the decision still needed. Do not commit, push, open or merge a pull request, or promote, on the strength of this skill alone.