give the agent a clean room and a task file.

Almost a year ago I wrote about modern agentic software engineering — everything is text, simple tools composed together. What’s changed since then? Better models, better agent harnesses. The ideas are the same but the execution actually works now. This post covers the first piece: workspaces.

My setup starts with $HOME/code — a directory of GitHub orgs, each containing their repos:

~/code/
  dkdc-io/
    zorto/        # static site generator
    db/           # database toolkit
    …
  lostmygithubaccount/
    dkdc.dev/     # this website
    bin/          # personal scripts
    …
  workspaces/     # agent workspaces live here

I start in root, write a task file, and spin up a workspace with an agent to execute on it. The agent gets a fresh clone, a clean branch, and a task file — fully isolated from my checkout and from other agents. That’s a workspace.

the problem #

You want an agent to fix a bug while you’re working in the same repo. Your checkout is occupied. Git worktrees share refs and index state — two agents rebasing at the same time will conflict. The answer is obvious once you see it: just clone the repo again. Disk is cheap and isolation is worth it.

the workspace #

workspaces/
  webapp/
    zorto/          # fresh clone on branch cody/ws-webapp
    TASK.md         # what the agent should do

A directory with fresh repo clones (branched from remote default) and a TASK.md with everything the agent needs to know. The whole abstraction is a folder.

the scripts #

Two scripts handle the lifecycle:

create-workspace --task tasks/webapp.md \
  --repo dkdc-io/zorto "webapp"

Clones the repo from origin, branches, writes TASK.md, and starts a tmux session running ai 'execute on @TASK.md'. You can pass multiple --repo flags if the agent needs context from related repos.

delete-workspace webapp

Kills the tmux session, deletes the directory. Clean.

the task file #

The task file is where context engineering happens. create-workspace generates it with metadata and appends your task content:

# dkdc workspace

workspace: **webapp**
branch: `cody/ws-webapp`

## repos

- `dkdc-io/zorto`

## task

Build a web-based CMS for zorto sites. Requirements:
- File browser for content/templates/sass
- Live preview with hot reload
- ...

The agent reads this on startup and knows: what repo it’s in, what branch it’s on, what it’s supposed to do. If your task file is good, the agent just works. If it’s bad, the agent drifts. The task file is the hard part.

why not worktrees #

Git worktrees share the .git directory, refs, and index state. Two agents rebasing at the same time will conflict. Shared stash, shared reflog — they step on each other. Deleting a worktree doesn’t fully clean up either.

Fresh clones are fully isolated. Each agent has its own .git, its own refs, its own world. A few hundred MB of disk per clone. Worth it.

origin #

I developed this pattern at Ascend, where we use “ASE workspaces” across all engineering. The problem scales — more engineers running more agents across more repos means isolation matters even more. The scripts here are my personal versions, but the concept is the same.

what’s next #

Workspaces give agents isolation. The next question is orchestration — how do you manage multiple workspace agents, monitor their progress, and intervene when they’re stuck? That’s tmux.