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

When I use coding agents for work larger than a single patch, a coding harness usually handles the individual activities well: exploring the repository, comparing designs, implementing a task, and reviewing the result. The awkward part is what has to survive 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 mainly because another 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.

Had verification failed, the task would instead have returned to implementation with the findings. Either way, the next session starts from the same brief and remaining tasks rather than from 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 or 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. The main interactions are:

• 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 from requirements and research through planning, execution, and verification. beads and its Rust port, beads_rust, were useful references for keeping dependency-aware work 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, which 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 one brief, task format, and set of authority rules across these methods. A finding does not become a task without a decision, and an implementation does not count as verified because its implementation agent says it is finished.

The same skill in different harnesses#

Codex, Claude Code, OpenCode, Pi, and Oh My Pi have different conventions for discovering skills, asking structured questions, defining commands, and delegating work to fresh agents. Zdev therefore renders the same workflow contract as a native integration for each harness:

• 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 marks the point at which the loop became stable enough in my own work to share. I will still make breaking changes, including new major versions, when my use of 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.