Z-mode playbooks

Invoke the installed mode explicitly: $z-mode in Codex or /z-mode in Claude Code, followed by a concrete request. These are natural-language requests, not subcommand syntax. The mode routes the request to one playbook and reads only that leaf; if none fits, it uses the installed figure-it-out skill to design a scoped workflow. It loads a principle only when that leaf changes a decision.

The mode remains active in conversation until stopped or replaced; it does not provide a scheduler. Simple work runs directly. Delegated workflows use native agents by default, or Herdr execution when explicitly enabled for the session. Herdr applies alongside every playbook below, including its companions, rather than adding a separate route. Both paths preserve bounded concurrency, exclusive ownership, artifact verification, and action authority. Native settings are inherited; independently launched CLIs have their own configuration. Missing independent coverage must be disclosed. See the mode source and execution contract.

Bundled tools are optional capabilities, not a runtime supplied by the mode. Resolve the real installed skill directory, use quoted absolute script paths, and retain the target repository as cwd. Run the plan validator (check_plan.py), worktree audit (worktree_audit.py), and PR watcher for GitHub and GitLab (watch-pr/watch_pr.py) with uv run. They require Python 3.12+ and use the standard library without installing dependencies beside the skill scripts. The existing shell launchers forward to uv. Consult each tool’s usage guidance; forge access, native delegation and durable background execution are separate prerequisites.

Investigation

Answer a read-only question about a runtime flow or design decision.

Codex: $z-mode Explain how session reuse works and why it skips startup commands.
Claude Code: /z-mode Explain how session reuse works and why it skips startup commands.

Trace the flow with how, consult why for motivation, compare relevant alternatives, and return a cited answer with gaps.

Prerequisites and limits: Read-only scope excludes edits, prototypes, and publication.

Supporting playbook.

Bug fix

Repair a reproduced defect.

Codex: $z-mode Fix the restart crash in the session loader.
Claude Code: /z-mode Fix the restart crash in the session loader.

Reproduce on the reported surface, trace callers and history, make the smallest root-cause fix, add a focused regression, and rerun the original repro. Return mechanism, fix, checks, and limits.

Prerequisites and limits: A missing runtime or harness must be reported as missing proof; publication needs its own request.

Supporting playbook.

Feature

Implement a scoped user-visible capability.

Codex: $z-mode Add filtering to the session picker.
Claude Code: /z-mode Add filtering to the session picker.

Ground entry points and contracts, choose a simple data shape, implement all affected consumers, and verify observable behavior. Return result, meaningful choices, proof, and open decisions.

Prerequisites and limits: Small tasks stay direct; native delegation is optional for exclusive independent seams. Commit and publication require covered authority.

Supporting playbook.

Refactoring

Change structure while holding behavior steady.

Codex: $z-mode Simplify the picker API without changing behavior.
Claude Code: /z-mode Simplify the picker API without changing behavior.

Pin behavior, remove redundant layers, migrate callers and references in coherent units, and verify equivalence on the actual artifact. Return the structural change and held contract.

Prerequisites and limits: Compilation alone is not equivalence; separately discovered product defects remain separate.

Supporting playbook.

Performance issue

Investigate and improve one measured performance complaint.

Codex: $z-mode Reduce picker latency on a 10000-session workload.
Claude Code: /z-mode Reduce picker latency on a 10000-session workload.

Capture a repeatable baseline, vet each number with benchmark-checklist, trace cost, change one mechanism, interleave baseline and treatment samples, and run correctness regressions. Return units, delta, method, and artifacts.

Prerequisites and limits: Use the same realistic workload; source inspection cannot prove a win. Use hillclimb for sustained optimization.

Supporting playbook.

Hillclimb

Run bounded measured optimization attempts.

Codex: $z-mode Hillclimb picker latency below 50 ms with a 30-minute budget.
Claude Code: /z-mode Hillclimb picker latency below 50 ms with a 30-minute budget.

Fix metric, workload, target, correctness floor, sampling and budget; vet the probe with benchmark-checklist before freezing it, including error and completed-work counts; record one hypothesis per isolated attempt in show-me-your-work; keep wins above noise. Return baseline/final, accepted and rejected attempts, and trail.

Prerequisites and limits: Requires a stable probe and decision trail. Stop at target, stop request, budget, or blocker; discard only this run's failed edits.

Supporting playbook.

Runtime forensics

Diagnose a live runtime signal.

Codex: $z-mode Diagnose the worker memory growth using a live heap capture.
Claude Code: /z-mode Diagnose the worker memory growth using a live heap capture.

Capture project instrumentation, reduce hot paths or retainers, confirm the mechanism with bounded instrumentation, and map to source. Return observations, hypotheses, evidence, and gaps.

Prerequisites and limits: Needs an accessible instrumented instance. Diagnosis does not authorize a fix or hot-patching production.

Supporting playbook.

Trace forensics

Diagnose a supplied profile, trace, or heap artifact.

Codex: $z-mode Explain the hot path in the supplied CPU profile.
Claude Code: /z-mode Explain the hot path in the supplied CPU profile.

Identify format, use an existing parser, query frames or retainers, map symbols to source, and compare paired captures when available. Return a cited diagnosis and artifact paths.

Prerequisites and limits: No fix or new production capture unless requested; without corroboration label the strongest supported hypothesis.

Supporting playbook.

Prototype

Settle an uncertain design decision with a throwaway experiment.

Codex: $z-mode Prototype two keyboard navigation layouts for the picker.
Claude Code: /z-mode Prototype two keyboard navigation layouts for the picker.

Name the decision, build minimal variants in scratch space, observe interaction or timing, and return evidence, tradeoffs, recommendation, and scratch path.

Prerequisites and limits: Visual choices need rendered evidence when available; scratch output is not production integration.

Supporting playbook.

Visual parity

Preserve rendered behavior during a migration.

Codex: $z-mode Migrate the dialog while preserving pixel-exact visual parity.
Claude Code: /z-mode Migrate the dialog while preserving pixel-exact visual parity.

Pin immutable baselines, states, viewport, fonts, and environment; migrate shared primitives first; compare with the image-diff harness and inspect interactions. Return per-state results and artifacts.

Prerequisites and limits: Needs stable baselines and a rendered comparison harness. Pixel-exact requests use zero tolerance; appearance alone is not proof.

Supporting playbook.

Skill authoring

Create or revise a portable skill.

Codex: $z-mode Author a skill for inspecting our release checks.
Claude Code: /z-mode Author a skill for inspecting our release checks.

Read callers and policy, keep one canonical folder, put conditional procedures in resources, resolve real installed paths, validate metadata and helpers, and run a realistic scoped scenario for behavior changes. Return local artifact and validation.

Prerequisites and limits: Preserve explicit-only host policy. Project discovery uses .agents/skills or .claude/skills; authoring does not authorize global installation, commits, messages, tickets, or PRs.

Supporting playbook.

Evaluation

Compare skill variants on real host behavior.

Codex: $z-mode Evaluate these two skill variants on the same bug-fix request.
Claude Code: /z-mode Evaluate these two skill variants on the same bug-fix request.

Define 3–6 held-out criteria, isolate candidate directories, issue identical unlabeled requests in native sessions, capture actual evidence, and use a fresh blind judge. Return rubric, receipts, verdict, and recommendation.

Prerequisites and limits: Needs supported native sessions and scoped history access. Without an independent judge mark parent-only evaluation; self-reports do not prove a skill was read.

Supporting playbook.

PR status and remediation

Check PR state or drive explicitly requested remediation.

Codex: $z-mode Check PR 42 status in one read-only pass.
Claude Code: /z-mode Check PR 42 status in one read-only pass.

Choose check, drive, threads-only, or requested background mode; resolve exact heads and reviews; triage findings against code; verify requested fixes and re-query the new head. Return state, remediation, checks, and blockers.

Prerequisites and limits: The PR watcher (GitHub via gh, GitLab via glab) is an optional Python tool launched with uv and requiring forge access; use its --help and absolute installed path. Read-only status excludes fixes and replies; merge-ready is not merged. Background requires a supported live runtime.

Supporting playbook.

Authorized landing

Land changes explicitly authorized for merge.

Codex: $z-mode Merge PR 42 when its current-head checks pass, using squash.
Claude Code: /z-mode Merge PR 42 when its current-head checks pass, using squash.

Pin dependencies and receipts, re-check current-head CI and reviews, land only the contiguous verified frontier, check trunk drift right before each merge, wait for confirmed merge, then refresh the next head. A child is retargeted only when the landing authority covers it; otherwise the needed retarget is reported. Return actual merges and remaining ceiling.

Prerequisites and limits: Requires explicit landing authority and forge access. Substantial behavior changes need independent verification where supported; no bypassing approvals or unsolicited verdict posts.

Supporting playbook.

Bounded autonomous task

Complete one bounded task continuously in the current session.

Codex: $z-mode Work until the failing import check passes, with a 30-minute limit.
Claude Code: /z-mode Work until the failing import check passes, with a 30-minute limit.

State done predicate, scope, budget and capabilities; make justified verified iterations; retain checkpoints via show-me-your-work; stop at verified done, stop, blocker, or limit. Return predicate state and remaining work.

Prerequisites and limits: Does not supply overnight scheduling or wider publication authority. If persistence ends, write the pause-safely handoff.

Supporting playbook.

Program coordination

Coordinate a program larger than one simple run.

Codex: $z-mode Coordinate the parser and UI migration with exclusive owners and verified handoffs.
Claude Code: /z-mode Coordinate the parser and UI migration with exclusive owners and verified handoffs.

The coordinator decides which agent does each piece of work, checks what each produces, and never writes code. One owner per PR carries it from build to merge within the authorized actions; only the owner pushes, rebases, or retargets it. Each PR needs a verifier from another model family at its current head. Pilot one unit before fan-out, read diffs rather than summaries, and check live PR state before reporting. Return what landed, each PR's live state and verdict, what was dropped, and the decisions waiting on the user.

Prerequisites and limits: Needs native delegation. State lives in the host's task tracker where available and a user-owned notes file; PR watching uses native event subscriptions where the host has them. No bundled bookkeeping CLI remains. Without an other-family verifier or merge authority, a PR stops at merge-ready. No durable runtime means handoff.

Supporting playbook.

Autonomous queue

Execute independent work items with explicit done predicates.

Codex: $z-mode Complete these three independent fixes and deliver local verified artifacts.
Claude Code: /z-mode Complete these three independent fixes and deliver local verified artifacts.

Pin scope, gates and authority; assign exclusive native owners; independently verify exact heads; publish or merge only covered items; reconcile children on stop. Only a demonstrated failure blocks an item; other findings become parked follow-ups. Return item, owner, status, head, evidence, remaining gates, and follow-ups.

Prerequisites and limits: Host concurrency and native reviewers bound coverage. A wording-only change that alters no behavior or instruction gets no extra verifier. The name grants no merge authority or permission to bypass operator gates.

Supporting playbook.

Autonomous queue, operator lands

Run the autonomous queue without merging, so you review and land the verified work.

Codex: $z-mode Build the schema then API then UI changes as a review stack; do not merge.
Claude Code: /z-mode Build the schema then API then UI changes as a review stack; do not merge.

Runs the autonomous queue's owners and verification, then stops when each item is verified at its current head with green CI where published. Independent items stay off trunk; an item stacks only on the item it builds on and rebases onto that parent's branch. A restacked child keeps its verdict when its git patch-id is unchanged. Return each item's verdict, head, and base.

Prerequisites and limits: Publication must be authorized: each chain's root targets trunk and children target parents. No merge or auto-merge, and no pushes after handoff without your go.

Supporting playbook.

Session pickup

Resume from a named handoff or prior session.

Codex: $z-mode Resume from .agent-work/import-fix/handoff.md.
Claude Code: /z-mode Resume from .agent-work/import-fix/handoff.md.

Read only named session evidence, reconstruct goal and state, refresh live Git/PR facts and load-bearing claims, then route remaining work. Return inherited versus refreshed proof and exact resume action.

Prerequisites and limits: Needs the named handoff or supported scoped history access; inherited summaries are not live evidence and authority does not expand.

Supporting playbook.

Pause safely

Preserve a resumable task at an explicit pause or runtime limit.

Codex: $z-mode Pause now and save a concrete resume note for the import fix.
Claude Code: /z-mode Pause now and save a concrete resume note for the import fix.

Stop at an atomic boundary, drain children, preserve all files, and write goal, active mode, authority, heads, dirty state, checks, decisions, blockers, and the first resume action. Return note and on-disk state.

Prerequisites and limits: No side-effect commit, push, or discard. Default note lives under .agent-work/<slug>; verify it survives teardown and refresh live state on resume.

Supporting playbook.

Multi-phase plan

Produce a verifiable phased plan before implementation.

Codex: $z-mode Plan the parser migration in docs/parser-plan.md; stop before implementation.
Claude Code: /z-mode Plan the parser migration in docs/parser-plan.md; stop before implementation.

Ground constraints, write Outcome, Scope, Phases, Risks and Handoff; give each phase Depends on, Files, Acceptance and Verification; run the bundled plan validator. Return path, dependencies, tradeoffs, and validator result.

Prerequisites and limits: Planning stays read-only apart from the requested plan. Validator needs Node and its real installed script path; no automatic implementation, fixed lane count, or overnight promise.

Supporting playbook.

Worktree audit and cleanup

Audit worktrees and remove only specifically authorized candidates.

Codex: $z-mode Audit this repository worktrees without removing any.
Claude Code: /z-mode Audit this repository worktrees without removing any.

Run the bundled audit for the explicit target repository, inspect each candidate's files, diffs, activity and history, then remove only authorized clean unused trees without force. Return held candidates and reclaimed space.

Prerequisites and limits: Audit needs Bash, Node and Git; optional --with-prs needs GitHub access. Buckets are advice, CLOSED is not merged, unknown history is not safe, and caches need separate scope.

Supporting playbook.

Requested PR publication

Publish a scoped change when asked.

Codex: $z-mode Commit these task files and open a draft PR against main.
Claude Code: /z-mode Commit these task files and open a draft PR against main.

Verify repository, branch, base and dirty state; check requirements; stage intended files; commit and publish within authority; write a concrete body and read back head, base and URL. Return publication link and validation.

Use the host's built-in PR tool for supported operations and forge or stack tooling for the rest. With no built-in tool, GitHub falls back to gh with a body file. Complete any required host attachment even when creation used a CLI.

Descriptions use ## Why, ## What changed, ## Scope, optional ## Tradeoffs and ## Blast Radius, and ## Verification, unless the repository template or user specifies another format. Keep each stack layer's description scoped to its own diff; root targets trunk and children target their parent branch.

Prerequisites and limits: Requires publication authority. Honor requested draft/ready status and repository policy; otherwise open ready and verify actual state. Opening a PR does not authorize merge, auto-merge, or background babysitting.

Supporting playbook.