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:

## 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:

Confirm canary has been checked where it runs and that its pull requests were reviewed.
Open a reviewed pull request from canary into main. Its body lists every change included.
Tag the release with a semantic version: vMAJOR.MINOR.PATCH. A fix increases PATCH, a new capability increases MINOR, a breaking change increases MAJOR.
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). Then describe the exact operation and its target with pre-push. 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. 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.