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 can be reviewed and tracked in Git like other files in the repository. 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 differ in what they are allowed to do. 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 differ in how they 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 the history changes.

What zdev 1.5 adds#

Zdev 1.5.0 installs workflow routes for implementation, verification, audits, and continuing an area. Codex, Claude Code, OpenCode, Pi, and Oh My Pi retain their harness-specific integrations, and Google Antigravity joins them with user- or workspace-scoped skills and sandboxed custom subagents.

The skill can also run a finite batch of compatible tasks in parallel. Each task gets an isolated worktree and an independent verification pass. Zdev then integrates the accepted work one task at a time and records one durable commit per task.

Task selection supports unattended-work and priority metadata. A loop can take a loosely described focus and choose from all ready tasks instead of always selecting the first task by number. Explicit trunk areas, a standing general area, lightweight slice briefs, and zdev next --any cover work that does not need another isolated branch or full area. Areas close explicitly when their objective is done.

Tasks can be routine, standard, or advanced. The complexity level controls the implementation role and whether the task gets a read-only planning pass. Named execution profiles separately choose model and reasoning settings for planners, implementers, and verifiers. A profile can apply globally, to one harness, or to one command. zdev plan uses the same routing for plan-only work.

Work-context snapshots keep full task and Git state out of worker responses. The workflow stores a compact reference and loads the exact context when a worker needs it. Before changing task state, it compares the current repository state with the snapshot. Small follow-up tasks and implementation splits use the same reviewed task model.

Briefs, slice briefs, tasks, and worker instructions follow Matt Pocock’s writing-for-agents method: shared meaning stays in one place, branch-specific details use reading pointers, and completion conditions are checkable. Human-facing prose follows Lauren Tan’s unslop method, with concrete facts, plain active language, and stable repository terms. Durable planning records and transient worker payloads have separate writing rules, so each retains the context appropriate to its job.

Existing records, tasks, and worker configuration remain valid. Run zdev skill install <harness> --force to refresh an installed integration. The zdev changelog has the release details.