Zdev user guide

Zdev keeps development work in small Markdown tasks and leaves agent execution to your coding harness. This guide takes one repository from installation to a completed zdev task.

For a short worked example, follow Your first zdev task. The command guide explains the requests you make in chat. For experiments and measured optimization, see the research guide.

1. Install zdev

Versioned binaries are available from the latest GitHub release. Follow the release notes for the binary installation steps.

For installation from source with a Rust toolchain, use Cargo:

cargo install --git https://github.com/zayenz/zdev --locked

From a local zdev checkout, use:

cargo install --path . --locked

Check the installation:

zdev --version

2. Check or install a user integration

Check the user-scoped integration for your harness:

zdev skill check codex --scope user

Replace codex with claude, opencode, pi, omp, or agy. Status ok means the integration is current. For missing or conflict, install or refresh it:

zdev skill install codex

User-scoped integrations work across repositories and do not require zdev to be initialized in the current project.

3. Initialize a repository

On the trunk branch, choose how to store the zdev planning record:

• Choose personal to keep the record in this clone. Add the exact entry /.zdev/ to .git/info/exclude; it stays local and will not travel to another clone or collaborator.
• Choose project when .zdev should be portable, reviewed, and shared. Leave it visible to Git and commit it with the repository.
• Choose pull-request when .zdev should be tracked and reviewed on the feature branch but omitted from the final squash-merged tree. Leave it visible to Git, commit it during review, and clean it before squash merge.

Integration scope is separate from record policy. After making the record choice, run:

zdev init --record personal # or: project, pull-request

Zdev records the current branch as trunk. If you need to correct it, run zdev config trunk <branch>.

Inspect settings with zdev config show or zdev config get <key>. Change them with config set and config unset. Worker changes report the command to refresh the integration; they do not rewrite installed files. Run zdev config --help for supported keys, scopes, and values.

If you prefer a checked-in integration, install it now that the repository is initialized:

zdev skill install codex --scope project --guidance auto

Replace codex with claude, opencode, pi, omp, or agy. Project installation puts harness-native files under .codex, .claude, .opencode, .pi, .omp, or .agents. The --guidance auto option uses a root AGENTS.md or creates .zdev/guidance.md; you can instead pass agents, zdev, or a repository-relative Markdown path. Edit that source, then refresh and check the integration:

zdev skill install codex --scope project --force
zdev skill check codex --scope project

For a pull-request record, run zdev cleanup squash on the clean feature branch immediately before squash merge. It deletes only tracked .zdev files and makes one plain Git commit without a Zdev-Change-Id. It requires a pull-request record, an attached feature branch, no Git operation in progress, and tracked .zdev files to remove. This prepares the final tree for squash merge. A normal merge or rebase that retains the feature commits also retains .zdev in reachable history.

4. Create an area

An area groups one objective and its tasks. By default it owns an isolated feature branch, which you create first:

git switch -c scheduling
zdev area create scheduling \
  --title "Scheduling support" \
  --objective "Add a tested scheduling API."

For a personal or project record, use --trunk to work on the configured trunk branch, which other trunk areas may also use:

git switch main
zdev area create scheduling \
  --title "Scheduling support" \
  --objective "Add a tested scheduling API." \
  --trunk

Trunk mode follows later project.trunk configuration changes dynamically. It does not weaken task ownership or stage unrelated trunk changes. Pull-request records remain isolated.

Zdev creates this structure:

.zdev/scheduling/
  area.toml
  brief.md
  TASKS.md
  tasks/

Write shared decisions in brief.md. During approved area shaping or an authorized investigation task, reusable research may live as separate files under background/. Keep only readable, stable, source-backed material that later tasks need; index every file from the brief and link only relevant files from tasks. Do not retain transcripts, raw tool or search dumps, repository source copies, temporary prototypes, or lifecycle metadata. The brief remains the authoritative synthesis, and each task remains the source of truth for its own outcome, boundaries, and done conditions. A standalone investigation stays report-only unless you ask to preserve its result.

For a larger area with several related increments, add lightweight slice briefs as needed:

zdev slice create scheduling api \
  --title "Scheduling API" \
  --objective "Expose the scheduling model through a stable API." \
  --boundary "Keep persistence out of this slice."
zdev slice list scheduling
zdev slice show scheduling api

Slice files live under .zdev/scheduling/slices/. They contain an objective and boundaries but no stored status. Tasks may name a slice, and zdev derives its ready, blocked, and done counts from those tasks, including zeros for an empty slice. Unsliced tasks remain valid and count only in area totals. Task selection reports the slice brief to read after the authoritative area brief.

Keep notes for future work

Use .zdev/_notes/ for unfinished plans, future extensions, open questions, and research you want to keep before deciding what work to pursue. Save one file per topic, or collect related documents in a folder with nested folders:

.zdev/_notes/
  search.md
  remote-workers/
    README.md
    initial-plan.md
    research/
      harness-comparison.md
      scheduling-options.md

There is no required template, metadata, status, or index. A folder README is optional and can describe its purpose or where to resume. Research documents can be saved together without first curating them into area background. Notes follow the repository’s existing record policy and stay outside area discovery and task selection.

Ask the skill in ordinary language:

Use zdev to add a note about remote workers.
Use zdev to save these research documents together in _notes/remote-workers/.
Use zdev to list notes.
Use zdev to list the contents of _notes/remote-workers/ recursively.
Use zdev to make an area from the remote-workers note folder.

These are skill routes, not new CLI commands. Adding a note saves the supplied material; listing notes is read-only and shows topic folders as collections by default. Making an area from a note follows the ordinary area and brief workflow. Useful source notes can be linked from the brief, and selected, stable research can move into indexed area background. Remaining material stays in _notes/. Source notes are kept unless you request cleanup. Creating the area alone does not create tasks or start implementation.

Keep one-off work in a general area

If you often have small, unrelated improvements, keep them in an ordinary area with the conventional tag general. First choose where it should live. For an isolated area, create or switch to its branch, then bind the area to the branch already checked out with:

git switch -c general
zdev area create general \
  --title "General work" \
  --objective "Keep concrete one-off improvements as reviewed tasks."

For a personal or project record that shares configured trunk, omit the new branch and add --trunk to the area command.

Maintain a short standing brief.md with the shared engineering boundaries, testing level, and validation commands. Each one-off task still needs its own clear outcome, context, boundaries, completion conditions, and validation. Most remain unsliced; add a slice only when several related tasks need one shared objective.

For example:

# General work

## Objective

Keep concrete one-off improvements as reviewed tasks.

## Boundaries

- Give every task a useful outcome, clear scope, and observable done proof.
- Preserve compatibility unless an approved task says otherwise.

## Testing

Focused coverage. Match test work to the behavior or risk in each task.

## Validation

- Run the repository's standard validation before completion.

You can ask the harness to discuss a concrete one-off request and draft its task bundle in the same interaction. When no product or testing choice remains, it may proceed directly to the exact bundle review without a separate research or full-brief pass. You approve that exact bundle or delegate creation and import. The harness works on the recorded branch, runs proportionate tests, verifies independently, completes the task, and commits the accepted changes. Area creation records the branch; it does not switch it for you.

5. Explore and discuss the objective

Zdev is the top-level trigger for its harness workflow. Mention zdev, $zdev, or the existing .zdev area when asking for help. Generic requests such as “explore this idea” or “review this repository” do not activate zdev by themselves.

Start by asking the harness to use zdev to explore the objective:

Use zdev to explore the scheduling objective and build up its brief.

Explore an objective starts in the current checkout, inspects the repository, compares useful paths, and builds or revises brief.md. Before an unrequested branch switch, branch creation, or worktree creation, the harness asks which workspace to use and reuses any choice you already made. wayfind and shape are aliases after zdev is active. Exploration presents the resulting brief for discussion; it creates tasks only when you also requested task creation. For non-trivial work, the normal next step is:

Use zdev to discuss the scheduling brief before we create tasks.

For implementation, the harness reuses a workspace you explicitly selected. Otherwise it uses a worktree as the authoritative checkout. Check the workspace reported before implementation and inspect results there. Read-only exploration starts in the current checkout.

You can also request a separate source worktree for one task. The worker edits and validates there; integration, independent verification, task completion, and the final accepted commit happen in the authoritative area checkout. Conflicts and unfinished work preserve both locations for recovery.

In Codex, you can explicitly request a parallel batch of at least two named ready tasks. Before it starts, choose the finite task list, destination branch, permission to create task worktrees and branches, a total worker-role limit, and cleanup preference. Zdev checks likely source overlap, shared interfaces, validation resources, repository instructions, and visible competing work. Compatible implementations may overlap in separate trees; integration and verification still happen one task and one commit at a time. Codex, Claude Code, and Pi support this route. OpenCode and Oh My Pi currently offer sequential Implement for this request.

Discuss the brief reads the brief and relevant indexed sources, then identifies choices that could materially change behavior, scope, task splitting, or validation. It resolves repository facts directly and works breadth first across the highest-impact choices. Each round asks up to three independent questions, using the harness’s structured question tool when available. It asks one focused question by default and batches only independent questions. An unanswered question is not consent. Discussion tests settled decisions against concrete scenarios, updates the brief after each round, and stops when no unresolved choice could materially change the work. grill is an alias.

Other active zdev intents route directly to Improve, Investigate, Create tasks, Implement, or Verify. After each interaction, zdev reports the result and relevant next actions. You can explicitly order several interactions in one message—for example, “approve this exact bundle and then implement.” Zdev then imports the unchanged approved bundle, validates it, and starts the next ready task if every implementation gate passes. Approval applies only to the artifact shown and does not imply another action.

6. Import reviewed tasks

Your harness sends the proposed task bundle to zdev to render for review:

zdev tasks review scheduling --from - --format json

Zdev stores the bundle and its Markdown review file in local Git administrative storage. The JSON result gives the harness a review ID and the file path. For non-trivial work, a fresh reviewer reads that Markdown file. If it suggests concrete revisions, the harness replaces the stored candidate. A focused correction is checked by the same reviewer against the prior findings and the complete revised document. A material change to scope, boundaries, dependencies, task splitting, or testing strategy receives a fresh full challenge. Storing or challenging a candidate does not approve it. The harness presents only the final challenged document for explicit approval by default with:

zdev tasks review scheduling --show

You approve the Markdown once. The harness carries the review ID and imports that exact version with zdev tasks import scheduling --reviewed <review-id>.

You can override this confirmation step: “create and import the tasks without asking me” delegates that decision for the stated scope. The harness still reviews and validates the bundle, then imports it and reports the allocated tasks. That authority persists through in-scope revisions and continuation; only choices outside it need another decision. Creating tasks alone does not authorize implementation. An AFK task may also split into useful smaller tasks within its existing outcome, boundaries, and testing without new approval.

Zdev rejects content that differs from the reviewed bundle. If it changed, the harness replaces the stored review and asks for approval again when you retained exact-bundle confirmation. Delegated in-scope revisions need no new approval. It does not reconstruct or resend the approved document. For manual input, direct import remains available: paste the JSON into zdev tasks import scheduling --from - and press Ctrl-D. --from path/to/tasks.json also works and leaves the source file in place. Zdev writes one Markdown file per task and regenerates TASKS.md. Edit task files, not the generated index.

For project and pull-request records, the harness adds --commit --format json to its stored-review import, including for the initial task split. Personal records keep using ordinary import. A manual direct import can use zdev tasks import scheduling --from - --commit --format json. Use ordinary import under any policy when you explicitly want the additions left uncommitted.

An initial managed commit includes the config, area metadata, brief, referenced slice briefs, new task files, and regenerated TASKS.md. If later approved work changes the area’s tracked brief.md, leave it unstaged. The committed import validates and includes the brief with the new task files and regenerated TASKS.md; no separate brief commit is needed. Unrelated staged and unstaged changes are preserved. The JSON result includes task IDs, paths, the commit hash, and the stable change ID. It also includes the complete ready frontier in stable task order.

7. Run the task loop

In your coding-agent chat, ask for one ready task:

Use zdev to implement the next task in scheduling.

The harness selects a task, implements it, runs the agreed validation, and asks a fresh agent to verify it. After a pass, it records completion and commits the accepted changes. One implementation request stops after that task. Ask for goal or loop when you want continuation across tasks.

The remaining commands in this section let you inspect or perform parts of that workflow manually.

Inspect the branch relationship and next ready task directly when needed:

zdev status scheduling --format json
zdev next scheduling --format json

The installed implementation workflow uses one read-only collection instead:

zdev work-context scheduling --format json

For open work this returns matching status and goal projections, HEAD, and the exact staged, unstaged, and untracked evidence. A validated closed area returns before branch and Git collection. The git_untracked map records content hashes for untracked regular files and targets for untracked symlinks, so edits to new files also invalidate a snapshot comparison. For an untracked nested Git repository, it records HEAD and the repository’s tracked and untracked changes, excluding ignored files.

To pass a compact reference between workers, store the context:

zdev work-context scheduling --store --format json
zdev work-context scheduling --show <snapshot-id> --format json
zdev work-context scheduling --compare <snapshot-id> --format json

--store saves the JSON in local Git administrative storage and returns a compact reference. --show reproduces the saved bytes. --compare collects fresh context and reports whether it matches. Before each decision, compare the snapshot or collect fresh state. Snapshots remain available throughout the workflow. Older open snapshots without untracked content evidence remain readable but compare unequal to fresh state; capture a new snapshot before verification.

With only an area, zdev ranks ready tasks by AFK suitability, priority, then numeric task ID. When you give a fuzzy loop focus, every supported harness reads the full ready frontier and chooses the best fit. The focus is guidance, not an exact filter, and is applied again after each commit.

Ask the harness to work on the returned task with zdev. It should:

1. implement against the task, area brief, and repository guidance;
2. verify the result in a fresh, read-only context with separate specification and repository-standards checks;
3. fix concrete failures and verify again; and
4. stop for a real blocker or mark the task ready for completion after both checks pass.

During an active authorized task, coordination may correct an incidental planner-written technical restriction when the agreed outcome requires another helper or file. It first checks the original baseline, explicit constraints, compatibility promises, and ownership, updates only the active brief or task, explains the adjustment, and captures fresh work-context. Changes to the outcome or acceptance criteria, explicit user constraints, and unclear ownership still require the user. Pending reviewed task bundles retain exact revision approval.

The installed workflow handles completion and staging after verification. If you are performing those steps manually, mark the task done and stage the accepted source changes:

zdev task done scheduling scheduling-001 \
  --summary "Implemented and independently verified the scheduling model." \
  --validation "Focused model tests passed."

git add <explicit-implementation-path>...

For a project or pull-request record, also stage the changed task file and index. Use the actual task path returned by zdev:

git add .zdev/scheduling/tasks/001-add-the-scheduling-model.md \
  .zdev/scheduling/TASKS.md

For a personal record, leave .zdev excluded. Then commit the staged changes:

zdev commit -m "feat: add scheduling model"

zdev commit adds a stable Zdev-Change-Id trailer. Repeat zdev next until the open queue is exhausted. Queue exhaustion does not close the objective; close it explicitly after reviewing the result:

zdev area close scheduling
# If more approved work appears later:
zdev area reopen scheduling

Task bundles may set complexity to routine, standard, or advanced; omission means standard. The harness never infers routine work. Advanced work gets one read-only plan before its first edit, while every route keeps a fresh independent standard verifier.

Activate zdev and ask it to loop or set a goal for an area when you explicitly want continuation across tasks. Both words select the same route. The harness reports each selected task and completed verified commit. Codex, Claude Code, and Oh My Pi can continue natively. OpenCode and Pi complete at most one task per invocation and return CONTINUE only after a commit and a fresh ready work-context.

Inspect or find a logical change after a rebase with:

zdev change inspect HEAD
zdev change lookup Z0123456789abcdef...

You can add tasks while this loop is running with the committed-import command from step 6. New task-only commits do not interrupt the selected task. Finish that task, then consider the additions at the next zdev next.

8. Keep the area current

Before selecting or completing work, require branch_status.task_work.safe in JSON status. If trunk advances while the checked-out branch, anchor, ancestry, and linear history remain valid, zdev reports one rebase advisory and allows ordinary task work to continue. Run the explicit rebase when you need current trunk changes or are preparing to integrate:

zdev area rebase scheduling

An explicit trunk area instead resolves current project.trunk on every operation. Require that branch to be checked out and safe, but do not request a rebase or freshness step. Keep exact area/task attribution when inspecting and staging changes shared on trunk.

If Git stops on a conflict, resolve and stage the files, then continue or abort:

zdev area rebase scheduling --continue
zdev area rebase scheduling --abort

See the workflow reference for dependent areas, base anchors, verification responsibilities, and recovery.

Harness notes

Codex

Codex uses one $zdev skill, collaboration agents, and a fresh verification context. A project integration lives under .codex/skills/zdev. Asking zdev to loop or set a goal uses Codex’s native goal when clear and falls back to one verified task only when inspection proved clear but native creation is unavailable.

Claude Code

Start Claude Code from the repository root and accept workspace trust for a project installation. The integration provides one zdev skill, scoped implementer and verifier agents, and packaged workflows used by the skill.

OpenCode

OpenCode installs one skill plus agents and route commands under .opencode. /zdev-plan <area> [planner-profile] plans the explicit next task read-only. Asking zdev to loop or set a goal completes at most one task and returns CONTINUE only after a verified commit when ready work remains. OpenCode discovers project skills when started from a subdirectory in the worktree. Its explicit parallel command checks the current Task surface before mutation. Foreground batches do not return coordinator control per completed child, so the command creates no task worktrees and offers sequential implementation.

Pi

Pi installs a skill, prompt templates, and the zdev_subagent extension under .pi. The extension starts a fresh child Pi process for each implementation or verification handoff and accepts a frozen role/profile/model/effort selection for each single or batch item. /zdev-plan <area> [planner-profile] stops after one read-only planner. Its explicit parallel prompt can bound initial planner and source-implementer children across assigned worktrees. A session-local run returns one result at a time; Pi integrates and verifies it before explicitly continuing queued work, then completes and commits each result serially. Goal and loop are the same bounded one-task continuation route. User installations use $PI_CODING_AGENT_DIR, or ~/.pi/agent when the variable is unset.

Oh My Pi

Oh My Pi is separate from plain Pi. It installs a skill and constrained native task agents under .omp and uses OMP’s built-in task and hub facilities. /zdev-plan <area> [planner-profile] invokes one blocking read-only planner. The root skill’s goal and loop route first checks for an unfinished OMP goal. If none exists, it uses a native goal when available or falls back to one verified task. An ambiguous goal state blocks the workflow. A user installation goes to $PI_CODING_AGENT_DIR, or ~/.omp/agent when the variable is unset.

OMP 17.2.15 may find the skill but miss user task agents when PI_CODING_AGENT_DIR relocates the user root. The install and check commands warn about this. Unset the variable or use a project install under .omp until upstream discovery is fixed.

Google Antigravity

Google Antigravity (agy) installs the zdev Skill under .agents/skills/zdev and its role subagents under .agents/agents/zdev-*/agent.md. The Skill is the workflow entrypoint; zdev keeps durable goal state in .zdev, while Antigravity’s invoke_subagent dispatches the planner, implementer, and verifier agents. Antigravity workflows are a legacy surface being migrated to Skills. User installations use ~/.gemini/config, or $ANTIGRAVITY_CONFIG_DIR when set.

Scoped worker choices

Choose a named profile for one zdev interaction or an authorized multi-task run without saving it as the default. Zdev resolves concrete role settings at the start and keeps them for that run, including retries and continuation. A one-off role choice overrides only that logical step. Task complexity still chooses the implementation role; it does not choose the profile.

In Codex, “plan next task with advanced planner” selects and snapshots the next ready task, returns a read-only plan with the selected planner model and effort, and stops. A later implementation request rechecks that exact task and reuses the plan only while its task requirements and baseline remain applicable.

Get help

Run zdev --help or zdev <command> --help. The task format documents every task field.