The AI agent harness: six conventions around every agent run

Claude Code and Codex CLI can read a repository, plan a change, write the code, and run the tests without a human in the loop. Run one bare in a terminal and the workflow is entirely on you: you write the prompt, create the branch, watch the run, review the diff, open the PR. For one agent on one task, that works. It stops working the moment you run agents in parallel or step away, the core problem an agentic IDE exists to solve.

A harness is the set of conventions and primitives wrapped around the agent so its output is easier to trust and cheap to discard. None of it replaces your judgement. All of it targets the three failure modes every unstructured agent eventually hits:

AIDEN ships six conventions built into every story’s lifecycle, from the kanban card to the pull request. Two are hard guarantees; four are best-effort defaults you can lean on but should not mistake for gates.

Git isolation: one worktree per story

Before an agent launches, AIDEN creates a dedicated branch and worktree for its story, the same isolation you would build by hand with:

git worktree add ../story-142 -b story-142

Because each agent gets a separate working directory on disk, parallel agents cannot touch each other’s files, and a bad run is disposable: delete the branch and worktree, and main is untouched. This is the deepest guarantee on the page and the reason cancellation is always clean. The full mechanics are in the parallel agents and git worktrees guide.

The spec approval gate

A story moves from Stories to Spec Review on the board: the AI drafts a spec, scope, files to touch, edge cases, and since v1.5.21 the agent is blocked from implementing until you approve it. Catching a wrong approach here costs an edit to a document, not a discarded run. Why specs beat prompts is its own topic, see spec-driven AI development.

Codebase context

AIDEN reads the whole project and builds a technical and business overview that every agent receives, alongside workspace tools, a file browser, terminal, git access. Project files like CLAUDE.md or AGENTS.md are picked up automatically. Guidance, not enforcement: the agent decides how much to read, the way a new engineer does.

In-loop test iteration

The agent can run your test suite in its worktree, Jest, pytest, cargo test, anything your project uses, and failure output flows back into its context, so it fixes and re-runs as part of the loop. This is a convention, not a gate: AIDEN does not inspect exit codes or refuse to open a PR. The story card shows what the agent ran; you decide.

LLM PR review and one-click PR

Before opening a PR you can trigger a separate model pass over the diff: correctness concerns, missed edge cases, drift from the spec. It is informational, ship, send the agent back, or discard. The one-click PR sits next to it; the whole story-to-PR path is covered in the AI PR automation workflow.

Mid-run cancellation

Click Stop on any story card and the run terminates, leaving the worktree exactly as the agent left it. Inspect the partial work, keep what is useful, or delete the branch. Git isolation makes this safe by construction, no shared state to clean up, no other agent affected.

The CLI is not the problem, AIDEN runs on top of it, as described in Claude Code orchestration. The difference is who does the workflow work: raw CLI puts the spec, branching, review, and PR on you; a chat-style IDE handles edits but not orchestration.