@0xgeorgemathew/zcode 0.4.4 → 0.5.1

package/lib/workspace.js

@@ -42,16 +42,16 @@ function workspaceRoot(cwd) {
 
 // Ownership patterns arrive relative to --cwd; store them relative to the
 // workspace root, posix-style, so every session compares like with like.
-function normalizeOwns(patterns, cwd, root) {
+function normalizeOwns(patterns, cwd, root, flag = '--owns') {
   const realCwd = fs.realpathSync(cwd);
   return patterns.map((raw) => {
     const pattern = String(raw).trim();
-    if (!pattern) throw new OwnershipError('--owns pattern must not be empty');
+    if (!pattern) throw new OwnershipError(`${flag} pattern must not be empty`);
     const abs = path.isAbsolute(pattern) ? pattern : path.join(realCwd, pattern);
     const rel = toPosix(path.relative(root, abs));
     if (rel === '' || rel === '.') return '**';
     if (rel.startsWith('../') || rel === '..' || path.isAbsolute(rel)) {
-      throw new OwnershipError(`--owns "${pattern}" is outside the workspace ${root}`);
+      throw new OwnershipError(`${flag} "${pattern}" is outside the workspace ${root}`);
     }
     return /[/\\]$/.test(pattern) && !hasWildcard(rel) ? `${rel}/**` : rel;
   });
@@ -150,10 +150,10 @@ function readLeases(dir) {
 // lease. Writing first and reading second means two sessions starting at
 // the same instant both see each other; the later (startedAt, id) backs
 // off, so exactly one proceeds.
-function acquireLease({ id, root, owns, allowOverlap = false, env = process.env }) {
+function acquireLease({ id, root, owns, touch = [], allowOverlap = false, env = process.env }) {
   const dir = leaseDir(root, env);
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  const mine = { id, pid: process.pid, root, owns, startedAt: Date.now() };
+  const mine = { id, pid: process.pid, root, owns, touch, startedAt: Date.now() };
   const file = path.join(dir, `${id}.json`);
   fs.writeFileSync(file, JSON.stringify(mine) + '\n', { mode: 0o600 });
 
@@ -166,6 +166,14 @@ function acquireLease({ id, root, owns, allowOverlap = false, env = process.env
     }
     others.push(lease);
   }
+  // --touch never reserves anything, but it may not edit what a live
+  // session owns (an empty ownership is the whole workspace). Not ordered by
+  // start time: the toucher is the one that has to step aside.
+  const touchConflicts = touch.length && !allowOverlap ? others.filter((o) => ownsOverlap(touch, o.owns)) : [];
+  if (touchConflicts.length) {
+    fs.rmSync(file, { force: true });
+    return { ok: false, conflicts: touchConflicts, others, touch: true };
+  }
   const conflicts = others.filter((o) => ownsOverlap(owns, o.owns));
   const blocking = conflicts.filter(
     (o) => o.startedAt < mine.startedAt || (o.startedAt === mine.startedAt && o.id < id)
@@ -183,7 +191,14 @@ function liveLeases(root, env = process.env) {
 
 // --- change tracking ----------------------------------------------------------
 
-const WALK_SKIP = new Set(['.git', 'node_modules', '.zcode', '.DS_Store']);
+// zcode's own per-session directories (<cwd>/.zcode/out/<id>, project skills)
+// are never changes of the task, at any depth. The Playwright MCP's scratch
+// dir (.playwright-mcp: console logs, page snapshots) written by --visual
+// verification is tooling output, not task output.
+const TOOL_DIRS = new Set(['.zcode', '.playwright-mcp']);
+const isZcodePath = (rel) => rel.split('/').some((seg) => TOOL_DIRS.has(seg));
+
+const WALK_SKIP = new Set(['.git', 'node_modules', '.zcode', '.playwright-mcp', '.DS_Store']);
 const WALK_LIMIT = 20000;
 const HASH_LIMIT = 8 * 1024 * 1024;
 
@@ -253,6 +268,7 @@ function snapshot(root) {
     try {
       const entries = new Map();
       for (const [rel, code] of gitStatus(root)) {
+        if (isZcodePath(rel)) continue;
         entries.set(rel, { code, sig: fileSignature(path.join(root, rel)) });
       }
       return { kind: 'git', root, head: gitHead(root), entries };
@@ -314,7 +330,7 @@ function diffSnapshots(before, after) {
   if (after.kind === 'git' && before.head && after.head && before.head !== after.head) {
     const seen = new Set(out.map((f) => f.path));
     for (const f of committedChanges(after.root, before.head, after.head)) {
-      if (!seen.has(f.path)) out.push({ ...f, committed: true });
+      if (!seen.has(f.path) && !isZcodePath(f.path)) out.push({ ...f, committed: true });
     }
     out.sort((a, b) => a.path.localeCompare(b.path));
   }
@@ -327,6 +343,7 @@ module.exports = {
   normalizeOwns,
   globToRegExp,
   isOwned,
+  isZcodePath,
   ownsOverlap,
   acquireLease,
   liveLeases,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xgeorgemathew/zcode",
-  "version": "0.4.4",
+  "version": "0.5.1",
   "description": "Lean GLM-5.3 execution engine for orchestrator agents: task contracts, independent sessions, zcode-run verification, structured handbacks, subagents, MCP, skills. Wraps the ZCode engine. Zero dependencies.",
   "license": "MIT",
   "private": false,

package/skills/README.md

@@ -1,6 +1,6 @@
 # Orchestrator skills
 
-These skills teach an orchestrating agent how to delegate work to zcode, run sessions in parallel, and read the handbacks. Both describe the same CLI; they differ only in runtime notes (tool timeouts for Claude Code, sandbox and network escalation for Codex).
+These skills teach an orchestrating agent to make the design and logic decisions once, delegate the implementation to zcode (one session with units, parallel sessions, or a plan), and read the compact handbacks, spending its own tokens only on decisions and exceptions. Both describe the same CLI; they differ only in runtime notes (tool timeouts for Claude Code, sandbox and network escalation for Codex).
 
 | platform | skill in this repo | format |
 |---|---|---|

package/skills/claude-code/zcode/SKILL.md

@@ -1,112 +1,142 @@
 ---
 name: zcode
-description: Delegate scoped implementation work to the zcode CLI (GLM-5.3 executor) and consume its verified handback. Use when you are orchestrating and want a page, component, fix or other bounded unit implemented and checked by an independent executor session — alone or several in parallel — while you keep product, design and planning decisions.
+description: Delegate scoped implementation work to the zcode CLI (GLM-5.3 executor, vision-capable, has Playwright) and consume its compact verified handback. Use when you are orchestrating: you make the product, design and logic decisions once, then zcode implements, tests, visually verifies and repairs — in one session with subagent units, several parallel sessions, or a dependency plan — while you spend tokens only on decisions and exceptions.
 ---
 
 # Operating zcode as an executor
 
-zcode is a CLI execution engine. You hand it a scoped task; it implements the task in its own session, runs your acceptance checks itself, repairs failures within a budget, and returns a structured handback. You stay the orchestrator. You decide what to build and how it should look, how to split the work, when to run sessions in parallel, and when to review. zcode decides routine implementation details within the scope you give it.
+zcode is a CLI execution engine. You decide; it builds. It implements a scoped task in its own session, runs your checks itself, screenshots and judges UI with its own vision when you ask, repairs failures within a budget, and returns a small structured handback.
 
-Check it is ready once per machine: `zcode doctor` (exit 3 means no key, so run `zcode login`; exit 4 means the engine is missing).
+**The point is token economy.** Your tokens go to decisions and exceptions. Everything mechanical — writing code, running builds and tests, reading diffs, looking at screenshots, fixing small failures — is zcode's. If you are doing any of that after dispatch, you are paying twice.
 
-## When to use it
+Check readiness once per machine: `zcode doctor` (exit 3 → `zcode login`; exit 4 → engine missing). Don't run `--help`: everything you need is here.
 
-- Use it for bounded implementation work with a clear outcome: one page, a few components, a bug fix, a refactor of a known area, a test suite for a module.
-- Don't use it for product or design decisions, open-ended exploration, or work you can't describe a finished state for. Decide those yourself first, then delegate the implementation.
-- Size each session so you could review its result in one sitting. Several small sessions beat one huge one, because each returns its own evidence.
+## The workflow
 
-## Writing the handoff
+1. **Read** the codebase as much as you need to plan. This is the one phase where reading files is expected.
+2. **Decide** everything a user could see or a system depends on (checklists below). Write the decisions down once, as decisions — a file such as `docs/decisions.md` that sessions receive with `--decisions @file`.
+3. **Shape** the work: one session with units, several sessions, or a plan (next section).
+4. **Preflight** (optional, recommended for anything large or ambiguous): `--preflight` makes zcode list every question it would otherwise guess. Answer them all in one edit to the decisions file.
+5. **Dispatch and wait** with `--detach` + `zcode wait`, or `zcode plan run` + `zcode plan wait`.
+6. **Handle exceptions only.** `completed` → move on. Anything else → read only what the brief shows, answer or adjust in one line with `zcode resume`.
 
-Only the objective is required. Add what the executor cannot infer:
+## Deciding: leave nothing open-ended
 
-| field | flag | give it when |
-|---|---|---|
-| objective | positional text | always: the outcome, not the steps |
-| acceptance | `--accept "…"` | you have criteria beyond "it works" |
-| checks | `--check "cmd"` | always if possible: shell commands zcode runs itself (build, tests, lint, a grep) |
-| owns | `--owns path/or/glob` | other sessions may touch the same repo |
-| files | `--file path` | specific files to read first |
-| context / design | `--context "…"` or `--context @notes.md` | design decisions, copy, references, constraints |
-| everything | `--task contract.json` | larger handoffs (keys: objective, scope, constraints, design, acceptance, checks, files, references, context, owns, limits, model, effort) |
+The executor implements binding decisions exactly and is told not to invent anything user-visible or behavioural. Gaps either block it (a round trip for you) or get the most conservative default. Close them up front.
 
-Rules that keep you in charge:
+**Front end:** palette (exact values), type families and scale, spacing scale, radii, iconography/illustration style; every section's layout and hierarchy at each breakpoint you care about; exact copy; component states (hover, focus, active, disabled, loading, empty, error); motion (what moves, property, distance, duration, easing, stagger, trigger, reduced-motion behaviour); accessibility (focus order, traps, labels, contrast floor); stack and libraries; performance budget.
 
-- Put design decisions in `design` (JSON) or `--context`, written as decisions ("Hero uses the dark palette; CTA right-aligned"). The executor is told to implement them exactly and to report `blocked` rather than invent product or design choices.
-- Make checks mechanical and fast. A task with no `--check` can only come back `unverified`.
-- Don't ask zcode to commit, push, or deploy unless you mean it. It won't by default.
+**Back end / logic:** data shapes and storage keys; API routes, payloads, status codes and errors; validation rules (exact regexes, ranges); state machines (steps, transitions, what persists, what resets); auth and permissions; idempotency and retries; what is mocked vs real; side effects that are forbidden.
 
-## Running sessions
+**Boundaries:** what the executor may choose freely (internal names, file structure, helpers) and what it must ask about.
 
-Your Bash tool times out (2 minutes by default, 10 at most), and real tasks usually take longer. Start them detached and wait in bounded slices:
+Write decisions as statements, not wishes: "Reveal: opacity 0→1 and translateY 16px→0, 400 ms, cubic-bezier(.2,.7,.2,1), 60 ms stagger, at 20% visibility; reduced motion: opacity only."
 
-```sh
-zcode task --detach --id <id> --cwd <repo> [flags] "<objective>"   # prints the id, returns at once
-zcode wait <id> --timeout-ms 540000 --json --quiet                  # exit 124 = still running: wait again
-```
+## Shaping the work
 
-You can also run a foreground `zcode task … --json --quiet` with `run_in_background: true` and read its single result line when you're notified. Quick tasks (well under 2 minutes) can run in the foreground directly.
+Pick the cheapest shape that keeps each session finishable without you.
 
-- `zcode status` lists sessions. `zcode status <id> --json` shows the state (`queued|running|finished|interrupted`), phase (`starting|executing|checking|repairing|reporting`), activity, recent events, and the result once finished. Use it only when you need it. You don't have to watch progress, and nothing waits for your approval.
-- `zcode cancel <id>` stops the turn and any running check; the session is recorded as `cancelled`.
-- `zcode resume <id> "<message>"` continues the same session with its context intact. Use it to answer questions, request follow-up changes, or continue after `interrupted`, `failed`, or `partial`. It accepts `--detach`, `--model`, `--effort`, `--timeout-ms`, and `--max-repairs`. The scope (`--cwd`, `--owns`, checks) stays as it was.
-- Pick your own `--id` values (`page-1`, `fix-auth`) so you can retry safely. A start with an existing id is refused (exit 2) instead of running the work twice.
+- **One session with units** when the pieces share context (one page's sections, one module's functions). `--unit "hero: …"` per piece; zcode gives each unit its own subagent and integrates.
+- **Several sessions** when pieces are independent and own disjoint paths. Launch them `--detach` in parallel; each may have its own units.
+- **A plan** when there are dependencies (scaffold → parallel features → integration). `zcode plan run plan.json` sequences and parallelises for you; you wait once.
 
-## Parallel sessions
+Parallel safety is automatic: each session gets `ZCODE_PORT`, `ZCODE_OUT`, `ZCODE_TMP` and `ZCODE_SESSION_ID`. Tell the first (scaffold) session to make dev-server ports, build output dirs and test artifacts honour them. Target repos should ignore `.zcode/`.
 
-- Each session has its own engine context, so nothing leaks between them.
-- Sessions in the same repo must declare disjoint `--owns`. An overlapping start is refused with exit 7, and the error names the conflicting session. Fix the split, wait, or give the session its own `git worktree` and point `--cwd` at it.
-- After the work, each handback lists changed files. Anything outside the session's ownership appears in `scopeViolations` and makes the result `partial`.
-- You integrate the results. zcode doesn't coordinate sessions with each other.
+## The handoff
 
-## Reading the handback
+| field | flag | give it when |
+|---|---|---|
+| objective | positional text | always: the outcome, not the steps |
+| decisions | `--decision "…"`, `--decisions @file` | always for anything user-visible or behavioural |
+| checks | `--check "cmd"` | always: build, typecheck, tests, lint, greps — zcode runs them itself |
+| visual | `--visual "criterion"`, `--viewport WxH`, `--serve "cmd"` | any UI work: zcode serves on $ZCODE_PORT, screenshots, judges and repairs |
+| units | `--unit "name: objective [owns a,b]"` | one session should fan out to subagents |
+| owns | `--owns path/glob` | always when other sessions may run in the same repo |
+| touch | `--touch path` | a small edit to a shared file no running session owns |
+| files | `--file path` | files to read first (don't also pass them as `--context @`) |
+| context | `--context "…"` / `--context @file` | background that isn't a decision |
+| acceptance | `--accept "…"` | criteria beyond checks and visuals |
+| everything | `--task contract.json` | keys: objective, scope, constraints, decisions, design, acceptance, checks, visual, viewports, units, files, references, context, owns, touch, limits, model, effort |
 
-The result (`--json`: one `{"type":"result"}` line) has `status`, `summary`, `changes.files`, `checks` (zcode's own runs, with output tails), `issues`, `questions`, `unresolved`, `notVerified`, `scopeViolations`, `subagents`, and `handback` (the executor's own claims).
+Model and effort: `--model glm-5.3` for real work (`flash` for trivial edits); `--effort low|high|max` (default `max`). Other values are refused before anything starts.
 
-| status | exit | what it means | what you do |
-|---|---|---|---|
-| `completed` | 0 | zcode's checks passed, executor reports done, scope respected | review on your own schedule; integrate |
-| `unverified` | 9 | executor says done, but there were no checks (or no usable handback) | verify yourself, or resume with a check added to the message |
-| `partial` | 8 | work remains, a criterion is unmet, or files changed outside scope | read `issues`/`unresolved`/`scopeViolations`; resume or re-scope |
-| `blocked` | 10 | needs you: see `questions` | decide, then `zcode resume <id> "<answer>"` |
-| `failed` | 8 / 5 / 124 | `error.kind`: `checks_failed` (still failing after repairs), turn/engine error, or `timeout` | read `checks[].output` / `error`; resume with guidance or re-scope |
-| `cancelled` | 130 | stopped | resume if wanted |
+## Running
 
-Trust `status`, `checks`, and `changes`. They come from what zcode observed. Treat `handback` and `summary` as the executor's report. A subagent's `success` only means it returned. zcode already verified the integrated result through your checks, so you don't need to review per subagent or per step.
+```sh
+zcode task --detach --id <id> --cwd <repo> [flags] "<objective>"   # prints the id, returns at once
+zcode wait <id…> --timeout-ms 540000 --json --quiet                # 124 = still running (one line each): wait again
+zcode wait <id…> --any --timeout-ms 540000 --json --quiet          # return on the first that finishes
+zcode resume <id> "<answer or follow-up>" --detach                 # same session, context intact
+zcode result <id> [--full]                                         # brief again, or the full record
+zcode cancel <id>
+```
 
-## Example: small task
+Plans:
 
 ```sh
-zcode task --id fix-typo --cwd ~/site --owns README.md \
-  --check "grep -q '^# Acme Docs' README.md" \
-  "Fix the misspelled top-level heading in README.md (should read 'Acme Docs')" --json --quiet
+zcode plan check plan.json
+zcode plan run plan.json --detach [--preflight]
+zcode plan wait <name> --timeout-ms 540000 --json   # one summary line per session; details only for non-completed
+zcode plan resume <name> ["<message>"]              # resume failed/partial, relaunch skipped
+zcode plan resume <name> --session <id> "<answer>"  # answer one blocked session
 ```
 
-Exit 0 means it's done. The result line shows the single changed file and the passing check.
+`plan.json`: `{"cwd"?, "decisions"?, "context"?, "files"?, "model"?, "effort"?, "sessions": [{"id", "after"?: [ids], ...contract keys}]}`. Top-level decisions/context/files go to every session; `@` entries are files relative to the plan. The plan name is the file basename (or `--id`). Sessions that can run at the same time must own disjoint paths; `plan check` enforces it. When an upstream session ends non-completed, its dependants are `skipped` until you `plan resume`.
 
-## Example: Page 1 and Page 2 in parallel
+Your Bash tool times out at 10 minutes; always wait in bounded slices. Run the wait with `run_in_background` if you have other planning to do.
 
-You've already decided the design. Each page gets its own session, its own scope, and its own checks:
+## Reading the brief
 
-```sh
-zcode task --detach --id page-1 --cwd ~/site --label "Home page" \
-  --owns src/pages/home/ --file src/theme.ts \
-  --context @specs/home.md \
-  --accept "Hero, three feature cards, footer CTA as specified" \
-  --check "npm run build" --check "npm test -- home" \
-  "Implement the Home page exactly as specified in the context"
-
-zcode task --detach --id page-2 --cwd ~/site --label "Pricing page" \
-  --owns src/pages/pricing/ --file src/theme.ts \
-  --context @specs/pricing.md \
-  --accept "Three plan cards, middle one highlighted; monthly/yearly toggle" \
-  --check "npm run build" --check "npm test -- pricing" \
-  "Implement the Pricing page exactly as specified in the context"
-
-zcode wait page-1 page-2 --timeout-ms 540000 --json --quiet   # repeat while exit is 124
+`--json` prints one compact line: `status`, `summary`, `files`, failing check tails, `questions`, `issues`, `unresolved`, `scopeViolations`, `touched`, `decisions`, `visual`, `units`, and `result` (path to the full record).
+
+| status | exit | do |
+|---|---|---|
+| `completed` | 0 | nothing. Skim `decisions` (the executor's own in-scope choices); veto with `resume` only if one is wrong |
+| `blocked` | 10 | answer `questions` (they come with options and a recommendation) via `zcode resume <id> "<answer>"`, and add the answer to your decisions file |
+| `partial` | 8 | read `issues` / `unresolved` / unmet `visual` / `scopeViolations`; resume with one-line guidance or re-scope |
+| `failed` | 8/5/124 | read the failing check `tail` or `error`; resume with guidance |
+| `unverified` | 9 | you forgot checks: resume with a check added |
+| `cancelled` | 130 | resume if wanted |
+
+## Hard rules after dispatch
+
+- Don't open files a `completed` session changed. Don't re-run checks it ran. Don't look at its screenshots.
+- Don't poll `status`; use `wait`.
+- Don't fix code yourself; `resume` the session with one line.
+- Need to know something about the result? `zcode result <id> --full` first; read code only as a last resort.
+- Don't ask zcode to commit, push, publish or deploy unless the user asked; when they did, make it its own final session gated on everything else being `completed`.
+
+## Example: a marketing one-pager with an application form
+
+You read the empty repo, decide the design system, copy, motion, form logic and demo constraints, and write `docs/decisions.md`. Then `plan.json`:
+
+```json
+{
+  "decisions": ["@docs/decisions.md"],
+  "model": "glm-5.3", "effort": "high",
+  "sessions": [
+    {"id": "scaffold", "owns": ["package.json", "package-lock.json", "index.html", "*.config.*", "tsconfig*.json", "src/app/**", "src/styles/**", "src/components/**", "e2e/smoke.spec.ts", ".gitignore"],
+     "objective": "Vite + React + TS scaffold, tokens, shared shell, stubs for src/landing and src/apply; dev/preview/e2e honour ZCODE_PORT and ZCODE_OUT",
+     "checks": ["npm run build", "npm test", "npm run e2e"]},
+    {"id": "landing", "after": ["scaffold"], "owns": ["src/landing/**", "e2e/landing.spec.ts"],
+     "objective": "All landing sections per the decisions",
+     "units": ["hero: …", "highlights: …", "products: …", "how: …", "charges: …", "faqs: …", "about-cta: …"],
+     "checks": ["npm run build", "npx playwright test e2e/landing.spec.ts"],
+     "visual": ["hero headline fits on two lines at 390px", "product cards align on one row at 1440px", "no text overlaps any circle motif"]},
+    {"id": "apply", "after": ["scaffold"], "owns": ["src/apply/**", "e2e/apply.spec.ts"],
+     "objective": "Application dialog: demo OTP, four steps, local draft, thank-you",
+     "checks": ["npm run build", "npm test -- apply", "npx playwright test e2e/apply.spec.ts"],
+     "visual": ["OTP code is visible on screen after entering a number", "step indicator shows the current step at 390px"]},
+    {"id": "integration", "after": ["landing", "apply"], "owns": ["src/App.tsx", "e2e/**"],
+     "objective": "Wire everything, full-page pass, fix integration issues",
+     "checks": ["npm run build", "npm test", "npm run e2e"],
+     "visual": ["full page at 390 and 1440 matches the decisions; motion respects reduced motion"]}
+  ]
+}
 ```
 
-If `page-2` comes back `blocked` with "Should yearly prices show the discount badge?", decide and run `zcode resume page-2 "Yes, show the 'Save 20%' badge on yearly." --detach`, then wait again. To run the pages one after another instead, start `page-2` after `page-1`'s handback. The shared `src/theme.ts` is passed with `--file` (read), not owned, so a change to it by either session would come back as a scope violation. If a page truly needs a shared change, make it yourself or give that file to exactly one session's `--owns`.
+`zcode plan check plan.json` → `zcode plan run plan.json --preflight` (read-only `<id>.pre` sessions; prints only the questions) → answer them once in the decisions file → `zcode plan run plan.json --detach` → `zcode plan wait plan --timeout-ms 540000 --json`. Your total involvement: the decisions, one answer pass, one summary.
 
 ## Exit codes
 
-0 completed · 2 usage (bad flag, contract, or duplicate id) · 3 no key · 4 no engine · 5 failed · 6 `agent` had no subagent · 7 workspace conflict / session busy · 8 partial or checks failing · 9 unverified · 10 blocked · 124 timeout (for `wait`: still running) · 130 cancelled.
+0 completed · 2 usage (bad flag, contract, plan, effort, or duplicate id) · 3 no key · 4 no engine · 5 failed · 6 `agent` had no subagent · 7 workspace conflict / session busy · 8 partial or checks failing · 9 unverified · 10 blocked · 124 timeout (for `wait`: still running) · 130 cancelled.

package/skills/codex/zcode/SKILL.md

@@ -1,114 +1,142 @@
 ---
 name: zcode
-description: Delegate scoped implementation work to the zcode CLI (GLM-5.3 executor) and consume its verified handback. Use when you are orchestrating and want a page, component, fix or other bounded unit implemented and checked by an independent executor session — alone or several in parallel — while you keep product, design and planning decisions.
+description: Delegate scoped implementation work to the zcode CLI (GLM-5.3 executor, vision-capable, has Playwright) and consume its compact verified handback. Use when you are orchestrating: you make the product, design and logic decisions once, then zcode implements, tests, visually verifies and repairs — in one session with subagent units, several parallel sessions, or a dependency plan — while you spend tokens only on decisions and exceptions.
 ---
 
 # Operating zcode as an executor
 
-zcode is a CLI execution engine. You hand it a scoped task; it implements the task in its own session, runs your acceptance checks itself, repairs failures within a budget, and returns a structured handback. You stay the orchestrator. You decide what to build and how it should look, how to split the work, when to run sessions in parallel, and when to review. zcode decides routine implementation details within the scope you give it.
+zcode is a CLI execution engine. You decide; it builds. It implements a scoped task in its own session, runs your checks itself, screenshots and judges UI with its own vision when you ask, repairs failures within a budget, and returns a small structured handback.
 
-Check it is ready once per machine: `zcode doctor` (exit 3 means no key, so run `zcode login`; exit 4 means the engine is missing).
+**The point is token economy.** Your tokens go to decisions and exceptions. Everything mechanical — writing code, running builds and tests, reading diffs, looking at screenshots, fixing small failures — is zcode's. If you are doing any of that after dispatch, you are paying twice.
 
-## When to use it
+Check readiness once per machine: `zcode doctor` (exit 3 → `zcode login`; exit 4 → engine missing). Don't run `--help`: everything you need is here.
 
-- Use it for bounded implementation work with a clear outcome: one page, a few components, a bug fix, a refactor of a known area, a test suite for a module.
-- Don't use it for product or design decisions, open-ended exploration, or work you can't describe a finished state for. Decide those yourself first, then delegate the implementation.
-- Size each session so you could review its result in one sitting. Several small sessions beat one huge one, because each returns its own evidence.
+## The workflow
 
-## Writing the handoff
+1. **Read** the codebase as much as you need to plan. This is the one phase where reading files is expected.
+2. **Decide** everything a user could see or a system depends on (checklists below). Write the decisions down once, as decisions — a file such as `docs/decisions.md` that sessions receive with `--decisions @file`.
+3. **Shape** the work: one session with units, several sessions, or a plan (next section).
+4. **Preflight** (optional, recommended for anything large or ambiguous): `--preflight` makes zcode list every question it would otherwise guess. Answer them all in one edit to the decisions file.
+5. **Dispatch and wait** with `--detach` + `zcode wait`, or `zcode plan run` + `zcode plan wait`.
+6. **Handle exceptions only.** `completed` → move on. Anything else → read only what the brief shows, answer or adjust in one line with `zcode resume`.
 
-Only the objective is required. Add what the executor cannot infer:
+## Deciding: leave nothing open-ended
 
-| field | flag | give it when |
-|---|---|---|
-| objective | positional text | always: the outcome, not the steps |
-| acceptance | `--accept "…"` | you have criteria beyond "it works" |
-| checks | `--check "cmd"` | always if possible: shell commands zcode runs itself (build, tests, lint, a grep) |
-| owns | `--owns path/or/glob` | other sessions may touch the same repo |
-| files | `--file path` | specific files to read first |
-| context / design | `--context "…"` or `--context @notes.md` | design decisions, copy, references, constraints |
-| everything | `--task contract.json` | larger handoffs (keys: objective, scope, constraints, design, acceptance, checks, files, references, context, owns, limits, model, effort) |
-
-Rules that keep you in charge:
+The executor implements binding decisions exactly and is told not to invent anything user-visible or behavioural. Gaps either block it (a round trip for you) or get the most conservative default. Close them up front.
 
-- Put design decisions in `design` (JSON) or `--context`, written as decisions ("Hero uses the dark palette; CTA right-aligned"). The executor is told to implement them exactly and to report `blocked` rather than invent product or design choices.
-- Make checks mechanical and fast. A task with no `--check` can only come back `unverified`.
-- Don't ask zcode to commit, push, or deploy unless you mean it. It won't by default.
+**Front end:** palette (exact values), type families and scale, spacing scale, radii, iconography/illustration style; every section's layout and hierarchy at each breakpoint you care about; exact copy; component states (hover, focus, active, disabled, loading, empty, error); motion (what moves, property, distance, duration, easing, stagger, trigger, reduced-motion behaviour); accessibility (focus order, traps, labels, contrast floor); stack and libraries; performance budget.
 
-## Running sessions
+**Back end / logic:** data shapes and storage keys; API routes, payloads, status codes and errors; validation rules (exact regexes, ranges); state machines (steps, transitions, what persists, what resets); auth and permissions; idempotency and retries; what is mocked vs real; side effects that are forbidden.
 
-zcode needs network access (the GLM API) and write access to `~/.zcode-cli` and the target repo. In a sandboxed Codex session, those commands may fail with sandbox or network errors. If they do, re-run the same command with escalated permissions instead of changing the command.
+**Boundaries:** what the executor may choose freely (internal names, file structure, helpers) and what it must ask about.
 
-Real tasks usually outlast a single shell call's timeout. Start them detached and wait in bounded slices:
+Write decisions as statements, not wishes: "Reveal: opacity 0→1 and translateY 16px→0, 400 ms, cubic-bezier(.2,.7,.2,1), 60 ms stagger, at 20% visibility; reduced motion: opacity only."
 
-```sh
-zcode task --detach --id <id> --cwd <repo> [flags] "<objective>"   # prints the id, returns at once
-zcode wait <id> --timeout-ms 540000 --json --quiet                  # exit 124 = still running: wait again
-```
+## Shaping the work
 
-Quick tasks can run in the foreground: `zcode task … --json --quiet` prints exactly one result line.
+Pick the cheapest shape that keeps each session finishable without you.
 
-- `zcode status` lists sessions. `zcode status <id> --json` shows the state (`queued|running|finished|interrupted`), phase (`starting|executing|checking|repairing|reporting`), activity, recent events, and the result once finished. Use it only when you need it. You don't have to watch progress, and nothing waits for your approval.
-- `zcode cancel <id>` stops the turn and any running check; the session is recorded as `cancelled`.
-- `zcode resume <id> "<message>"` continues the same session with its context intact. Use it to answer questions, request follow-up changes, or continue after `interrupted`, `failed`, or `partial`. It accepts `--detach`, `--model`, `--effort`, `--timeout-ms`, and `--max-repairs`. The scope (`--cwd`, `--owns`, checks) stays as it was.
-- Pick your own `--id` values (`page-1`, `fix-auth`) so you can retry safely. A start with an existing id is refused (exit 2) instead of running the work twice.
+- **One session with units** when the pieces share context (one page's sections, one module's functions). `--unit "hero: …"` per piece; zcode gives each unit its own subagent and integrates.
+- **Several sessions** when pieces are independent and own disjoint paths. Launch them `--detach` in parallel; each may have its own units.
+- **A plan** when there are dependencies (scaffold → parallel features → integration). `zcode plan run plan.json` sequences and parallelises for you; you wait once.
 
-## Parallel sessions
+Parallel safety is automatic: each session gets `ZCODE_PORT`, `ZCODE_OUT`, `ZCODE_TMP` and `ZCODE_SESSION_ID`. Tell the first (scaffold) session to make dev-server ports, build output dirs and test artifacts honour them. Target repos should ignore `.zcode/`.
 
-- Each session has its own engine context, so nothing leaks between them.
-- Sessions in the same repo must declare disjoint `--owns`. An overlapping start is refused with exit 7, and the error names the conflicting session. Fix the split, wait, or give the session its own `git worktree` and point `--cwd` at it.
-- After the work, each handback lists changed files. Anything outside the session's ownership appears in `scopeViolations` and makes the result `partial`.
-- You integrate the results. zcode doesn't coordinate sessions with each other.
+## The handoff
 
-## Reading the handback
+| field | flag | give it when |
+|---|---|---|
+| objective | positional text | always: the outcome, not the steps |
+| decisions | `--decision "…"`, `--decisions @file` | always for anything user-visible or behavioural |
+| checks | `--check "cmd"` | always: build, typecheck, tests, lint, greps — zcode runs them itself |
+| visual | `--visual "criterion"`, `--viewport WxH`, `--serve "cmd"` | any UI work: zcode serves on $ZCODE_PORT, screenshots, judges and repairs |
+| units | `--unit "name: objective [owns a,b]"` | one session should fan out to subagents |
+| owns | `--owns path/glob` | always when other sessions may run in the same repo |
+| touch | `--touch path` | a small edit to a shared file no running session owns |
+| files | `--file path` | files to read first (don't also pass them as `--context @`) |
+| context | `--context "…"` / `--context @file` | background that isn't a decision |
+| acceptance | `--accept "…"` | criteria beyond checks and visuals |
+| everything | `--task contract.json` | keys: objective, scope, constraints, decisions, design, acceptance, checks, visual, viewports, units, files, references, context, owns, touch, limits, model, effort |
 
-The result (`--json`: one `{"type":"result"}` line) has `status`, `summary`, `changes.files`, `checks` (zcode's own runs, with output tails), `issues`, `questions`, `unresolved`, `notVerified`, `scopeViolations`, `subagents`, and `handback` (the executor's own claims).
+Model and effort: `--model glm-5.3` for real work (`flash` for trivial edits); `--effort low|high|max` (default `max`). Other values are refused before anything starts.
 
-| status | exit | what it means | what you do |
-|---|---|---|---|
-| `completed` | 0 | zcode's checks passed, executor reports done, scope respected | review on your own schedule; integrate |
-| `unverified` | 9 | executor says done, but there were no checks (or no usable handback) | verify yourself, or resume with a check added to the message |
-| `partial` | 8 | work remains, a criterion is unmet, or files changed outside scope | read `issues`/`unresolved`/`scopeViolations`; resume or re-scope |
-| `blocked` | 10 | needs you: see `questions` | decide, then `zcode resume <id> "<answer>"` |
-| `failed` | 8 / 5 / 124 | `error.kind`: `checks_failed` (still failing after repairs), turn/engine error, or `timeout` | read `checks[].output` / `error`; resume with guidance or re-scope |
-| `cancelled` | 130 | stopped | resume if wanted |
+## Running
 
-Trust `status`, `checks`, and `changes`. They come from what zcode observed. Treat `handback` and `summary` as the executor's report. A subagent's `success` only means it returned. zcode already verified the integrated result through your checks, so you don't need to review per subagent or per step.
+```sh
+zcode task --detach --id <id> --cwd <repo> [flags] "<objective>"   # prints the id, returns at once
+zcode wait <id…> --timeout-ms 540000 --json --quiet                # 124 = still running (one line each): wait again
+zcode wait <id…> --any --timeout-ms 540000 --json --quiet          # return on the first that finishes
+zcode resume <id> "<answer or follow-up>" --detach                 # same session, context intact
+zcode result <id> [--full]                                         # brief again, or the full record
+zcode cancel <id>
+```
 
-## Example: small task
+Plans:
 
 ```sh
-zcode task --id fix-typo --cwd ~/site --owns README.md \
-  --check "grep -q '^# Acme Docs' README.md" \
-  "Fix the misspelled top-level heading in README.md (should read 'Acme Docs')" --json --quiet
+zcode plan check plan.json
+zcode plan run plan.json --detach [--preflight]
+zcode plan wait <name> --timeout-ms 540000 --json   # one summary line per session; details only for non-completed
+zcode plan resume <name> ["<message>"]              # resume failed/partial, relaunch skipped
+zcode plan resume <name> --session <id> "<answer>"  # answer one blocked session
 ```
 
-Exit 0 means it's done. The result line shows the single changed file and the passing check.
+`plan.json`: `{"cwd"?, "decisions"?, "context"?, "files"?, "model"?, "effort"?, "sessions": [{"id", "after"?: [ids], ...contract keys}]}`. Top-level decisions/context/files go to every session; `@` entries are files relative to the plan. The plan name is the file basename (or `--id`). Sessions that can run at the same time must own disjoint paths; `plan check` enforces it. When an upstream session ends non-completed, its dependants are `skipped` until you `plan resume`.
 
-## Example: Page 1 and Page 2 in parallel
+Real tasks outlast a single shell call; always wait in bounded slices. zcode needs network access (the GLM API) and write access to `~/.zcode-cli` and the target repo: in a sandboxed Codex session, if a command fails with a sandbox or network error, re-run the same command with escalated permissions instead of changing it.
 
-You've already decided the design. Each page gets its own session, its own scope, and its own checks:
+## Reading the brief
 
-```sh
-zcode task --detach --id page-1 --cwd ~/site --label "Home page" \
-  --owns src/pages/home/ --file src/theme.ts \
-  --context @specs/home.md \
-  --accept "Hero, three feature cards, footer CTA as specified" \
-  --check "npm run build" --check "npm test -- home" \
-  "Implement the Home page exactly as specified in the context"
-
-zcode task --detach --id page-2 --cwd ~/site --label "Pricing page" \
-  --owns src/pages/pricing/ --file src/theme.ts \
-  --context @specs/pricing.md \
-  --accept "Three plan cards, middle one highlighted; monthly/yearly toggle" \
-  --check "npm run build" --check "npm test -- pricing" \
-  "Implement the Pricing page exactly as specified in the context"
-
-zcode wait page-1 page-2 --timeout-ms 540000 --json --quiet   # repeat while exit is 124
+`--json` prints one compact line: `status`, `summary`, `files`, failing check tails, `questions`, `issues`, `unresolved`, `scopeViolations`, `touched`, `decisions`, `visual`, `units`, and `result` (path to the full record).
+
+| status | exit | do |
+|---|---|---|
+| `completed` | 0 | nothing. Skim `decisions` (the executor's own in-scope choices); veto with `resume` only if one is wrong |
+| `blocked` | 10 | answer `questions` (they come with options and a recommendation) via `zcode resume <id> "<answer>"`, and add the answer to your decisions file |
+| `partial` | 8 | read `issues` / `unresolved` / unmet `visual` / `scopeViolations`; resume with one-line guidance or re-scope |
+| `failed` | 8/5/124 | read the failing check `tail` or `error`; resume with guidance |
+| `unverified` | 9 | you forgot checks: resume with a check added |
+| `cancelled` | 130 | resume if wanted |
+
+## Hard rules after dispatch
+
+- Don't open files a `completed` session changed. Don't re-run checks it ran. Don't look at its screenshots.
+- Don't poll `status`; use `wait`.
+- Don't fix code yourself; `resume` the session with one line.
+- Need to know something about the result? `zcode result <id> --full` first; read code only as a last resort.
+- Don't ask zcode to commit, push, publish or deploy unless the user asked; when they did, make it its own final session gated on everything else being `completed`.
+
+## Example: a marketing one-pager with an application form
+
+You read the empty repo, decide the design system, copy, motion, form logic and demo constraints, and write `docs/decisions.md`. Then `plan.json`:
+
+```json
+{
+  "decisions": ["@docs/decisions.md"],
+  "model": "glm-5.3", "effort": "high",
+  "sessions": [
+    {"id": "scaffold", "owns": ["package.json", "package-lock.json", "index.html", "*.config.*", "tsconfig*.json", "src/app/**", "src/styles/**", "src/components/**", "e2e/smoke.spec.ts", ".gitignore"],
+     "objective": "Vite + React + TS scaffold, tokens, shared shell, stubs for src/landing and src/apply; dev/preview/e2e honour ZCODE_PORT and ZCODE_OUT",
+     "checks": ["npm run build", "npm test", "npm run e2e"]},
+    {"id": "landing", "after": ["scaffold"], "owns": ["src/landing/**", "e2e/landing.spec.ts"],
+     "objective": "All landing sections per the decisions",
+     "units": ["hero: …", "highlights: …", "products: …", "how: …", "charges: …", "faqs: …", "about-cta: …"],
+     "checks": ["npm run build", "npx playwright test e2e/landing.spec.ts"],
+     "visual": ["hero headline fits on two lines at 390px", "product cards align on one row at 1440px", "no text overlaps any circle motif"]},
+    {"id": "apply", "after": ["scaffold"], "owns": ["src/apply/**", "e2e/apply.spec.ts"],
+     "objective": "Application dialog: demo OTP, four steps, local draft, thank-you",
+     "checks": ["npm run build", "npm test -- apply", "npx playwright test e2e/apply.spec.ts"],
+     "visual": ["OTP code is visible on screen after entering a number", "step indicator shows the current step at 390px"]},
+    {"id": "integration", "after": ["landing", "apply"], "owns": ["src/App.tsx", "e2e/**"],
+     "objective": "Wire everything, full-page pass, fix integration issues",
+     "checks": ["npm run build", "npm test", "npm run e2e"],
+     "visual": ["full page at 390 and 1440 matches the decisions; motion respects reduced motion"]}
+  ]
+}
 ```
 
-If `page-2` comes back `blocked` with "Should yearly prices show the discount badge?", decide and run `zcode resume page-2 "Yes, show the 'Save 20%' badge on yearly." --detach`, then wait again. To run the pages one after another instead, start `page-2` after `page-1`'s handback. The shared `src/theme.ts` is passed with `--file` (read), not owned, so a change to it by either session would come back as a scope violation. If a page truly needs a shared change, make it yourself or give that file to exactly one session's `--owns`.
+`zcode plan check plan.json` → `zcode plan run plan.json --preflight` (read-only `<id>.pre` sessions; prints only the questions) → answer them once in the decisions file → `zcode plan run plan.json --detach` → `zcode plan wait plan --timeout-ms 540000 --json`. Your total involvement: the decisions, one answer pass, one summary.
 
 ## Exit codes
 
-0 completed · 2 usage (bad flag, contract, or duplicate id) · 3 no key · 4 no engine · 5 failed · 6 `agent` had no subagent · 7 workspace conflict / session busy · 8 partial or checks failing · 9 unverified · 10 blocked · 124 timeout (for `wait`: still running) · 130 cancelled.
+0 completed · 2 usage (bad flag, contract, plan, effort, or duplicate id) · 3 no key · 4 no engine · 5 failed · 6 `agent` had no subagent · 7 workspace conflict / session busy · 8 partial or checks failing · 9 unverified · 10 blocked · 124 timeout (for `wait`: still running) · 130 cancelled.