zdev 1.0: yet another agentic loop, this one is mineDRAFT

When I use coding agents for work larger than a single patch, the coding harness usually handles each activity well. It can explore the repository, compare designs, implement a task, and review the result. The awkward part is keeping the work coherent between sessions.

There are many systems for running agentic loops. I have built one too. Building one is starting to feel like the agentic-development equivalent of the web-development “write a blog” starter project.

zdev 1.0 is my version. It is an open source command-line tool and agent skill. I published it because a concrete example may be useful to people building their own workflows.

Zdev keeps a small development loop in the repository. An area represents one coherent objective. It contains a brief for decisions shared across the work and individual Markdown files for the implementation tasks.

A small example#

Suppose I want to add CSV export to a scheduling application. A condensed version of the first interaction might look like this:

Me: Use zdev to explore adding CSV export for the schedule currently
shown to the user.

Agent: I found two export paths in the repository, but neither uses the
filters from the schedule view. Before I finish the brief:

1. Should the export contain all assignments or only the visible ones?
2. Should timestamps retain the schedule's stored time zone or use UTC?
3. Should exporting require the same permission as viewing the schedule?

Me: Use the visible assignments and require the same permission as the
schedule view. Retain the schedule's stored time zone; my reasoning is
the same as in:
https://codeblog.jonskeet.uk/2019/03/27/storing-utc-is-not-a-silver-bullet/

Agent: I created the schedule-export area and recorded those decisions
in its brief.

Once I agree with the brief, I ask zdev to turn it into tasks:

Me: Create tasks for the schedule-export area.

Agent: Prepared three tasks for review:

schedule-export-001  Add the CSV serializer and tests
schedule-export-002  Add the authenticated download endpoint
                   depends on: schedule-export-001
schedule-export-003  Add the export button and error handling
                   depends on: schedule-export-002

Import this task bundle?

Me: Yes.

I can end the session there. Later, I only need to ask for the next task:

Me: Use zdev to implement the next task.

Agent: Selected schedule-export-001. The implementation agent added the
serializer and tests. A fresh agent verified the task against the diff
and repository rules: PASS.

Completed schedule-export-001 and recorded commit 4c12a9e.

If verification had failed, the task would have returned to implementation with the findings. Either way, the next session starts from the same brief and remaining tasks. It does not depend on my recollection of the earlier conversation.

If I want the agent to continue until the whole area is done, I can also set a goal:

Me: Set a goal to use zdev to run the schedule-export area until all
tasks are complete.

The goal belongs to the agent, not to zdev. It tells the agent to keep selecting, implementing, and verifying tasks until the area is complete; zdev supplies the durable state and the next ready task.

The loop#

I leave judgment to the agent and bookkeeping to the binary. The agent decides whether a module boundary is sensible and whether a test demonstrates the right behavior. The program checks task structure and dependencies, binds an import to the task bundle I reviewed, regenerates the index, and selects a ready task.

Zdev stores only the state that needs to persist: metadata, the area brief, individual task files, and a generated task index. It does not store model transcripts or maintain a second execution database beside Git.

For an area named scheduling, the files look like this:

.zdev/
├── config.toml
├── guidance.md                 # optional repository guidance
└── scheduling/
    ├── area.toml               # objective, branch, and base metadata
    ├── brief.md                # decisions shared by the whole area
    ├── TASKS.md                # generated task index
    └── tasks/
        ├── scheduling-001.md
        ├── scheduling-002.md
        └── scheduling-003.md

The brief and task files fit ordinary code review and Git history. TASKS.md is generated, so each task has one authoritative file.

The complete task loop is:

Using the zdev skill#

I ask the coding harness to use zdev, then describe the work in ordinary language. Depending on what I ask for, the skill follows one of these paths:

• Explore an objective inspects the repository, compares plausible paths, and creates or revises the area brief.
• Discuss the brief challenges choices that could change behavior, scope, task boundaries, or validation.
• Improve surveys the codebase without changing it and returns vetted candidate work.
• Investigate answers one named uncertainty through research, diagnosis, or a disposable prototype.
• Create tasks turns an agreed brief into tasks with explicit dependencies and done conditions. I review the exact rendered bundle before zdev imports it.
• Implement selects the next ready task and delegates it within its declared boundaries.
• Verify gives the task, diff, and repository rules to a fresh agent. A failed review returns to implementation. Only a pass allows completion and commit.

The interactions share a brief and task model, but have different authority. An investigation can inform a decision without changing production code. An improvement finding becomes an objective only when I choose it. Verification cannot redefine the task it reviews.

What I borrowed#

Zdev combines ideas from several sources. Get Shit Done, now maintained as GSD Core, provided the path through requirements, research, planning, execution, and verification. beads and its Rust port, beads_rust, showed how dependency-aware work can live in a repository. Matt Pocock’s agent skills supplied methods for discussion, codebase exploration, task decomposition, investigation, and separate implementation review. Zdev also adapts shadcn’s Improve skill. That skill surveys a codebase, vets its findings, and stops before the audit turns into implementation.

I originally used these as separate tools and skills. Their boundaries overlapped: planning produced one artifact, issue tracking expected another, and implementation assumed a third workflow. Each skill also had different rules for when it could change the repository.

Zdev uses the same brief, task format, and authority rules across these methods. A finding becomes a task only after I make that decision. An implementation counts as verified only after a separate agent has checked it.

The same skill in different harnesses#

Codex, Claude Code, OpenCode, Pi, and Oh My Pi disagree on how to discover skills, ask structured questions, define commands, and delegate work to fresh agents. Zdev renders the same workflow contract as a native integration for each one:

• Codex uses collaboration agents, including a fresh context for verification.
• Claude Code defines scoped implementer and verifier agents, plus zdev task and audit commands.
• OpenCode installs a skill, agents, and /zdev-task and /zdev-audit commands.
• Pi installs prompt templates and an extension that starts a fresh child process for implementation or verification.
• Oh My Pi uses constrained native task agents and OMP’s task and hub facilities.

The task format, approval boundary, independent-verification rule, and zdev commands remain the same. Discussion uses the harness’s question mechanism when one is available.

An integration can be user-scoped for use across repositories or project-scoped and checked into one repository. Project installations also render the repository’s own guidance into the harness files. Each agent then receives the applicable build, test, generated-file, and safety rules without making those rules part of zdev itself.

Installing zdev#

Zdev is a Rust binary for macOS and Linux on x86-64 and Arm64. Versioned binaries are available from the GitHub release. It is also published on crates.io:

cargo install zdev --locked

The release binaries do not require a Rust toolchain and are the simpler option for normal use.

The same binary installs the integration for the coding harness:

zdev skill install codex
# or: claude, opencode, pi, omp

The integration can be installed for one user or checked into a project. The installed skill and the command-line contract then come from the same zdev version, without a separate prompt repository to keep in sync.

I maintain zdev in public as a personal tool. Version 1.0 is the point where the loop became stable enough in my own work to share. I will still make breaking changes, including new major versions, when using the tool exposes a better design.

The parts I expect to keep are durable briefs and tasks, reviewed task import, explicit implementation and independent verification, and Git commits that remain identifiable as history changes shape.

What changed after the first release#

Two weeks after version 1.0, zdev reached version 1.2.3. Claude Code changed most visibly. The 1.0 integration installed commands and worker roles. It now also installs native workflows for implementation, verification, audits, and continuing an area.

I first tried putting all of zdev inside one native Claude Code workflow. It worked, but it was too opaque: from the enclosing Claude session, it was hard to tell which part of zdev was running. The current integration uses narrower workflows instead. One completes a task, while another continues an area one task at a time. Their progress displays name each stage as it happens.

Task selection has become more deliberate. Tasks can be routine, standard, or advanced, which controls the worker used and whether the task gets a separate read-only planning pass. AFK and priority metadata help choose unattended work, and a loop can take a fuzzy focus instead of always selecting the first ready task by number. Trunk areas and lightweight slice briefs cover the smaller jobs for which creating a branch and full area always felt excessive.

The workers behind those levels are configurable for each harness. The configuration sets the model and reasoning level for roles such as the routine implementer, standard implementer, planner, advanced implementer, and verifier. It can provide user-level defaults and override them for one project. Routine work can therefore use a faster or cheaper model, while planning, advanced implementation, and independent verification get more capacity.

Many of the smaller releases came from watching workflows stop for bad reasons. An agent put valid JSON in a Markdown fence. A planner included a useful note next to its plan. A commit ID arrived in backticks. A branch was stale but safe to use. These cases now pass without relaxing checks for malformed or ambiguous results.

Work-context snapshots have also replaced much of the full task and Git diff that used to travel through model output. The workflow compares fresh repository state with the stored snapshot before it changes task state. Recent fixes make the loop retry directly actionable work when an implementer calls it blocked, but stop once repeated attempts make no attributable progress. In practice, unattended runs now stop for a real gate or because the work is stuck, rather than because one agent formatted its answer differently from another.

The zdev changelog has the release-by-release details.