# Using the Agent Workbench for Real Repository Tasks: A Complete Implementation Guide

> Safely run autonomous AI agents in any Git repository with the Agent Workbench. This guide details its simple framework for real repository tasks, enabling declarative routing and durable state storage.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: how-to-guide
- Published: 2026-06-24

---

**The Agent Workbench is a minimal, three-file framework that enables autonomous AI agents to operate safely inside any Git repository by providing a declarative router, durable state storage, and a JSON task board.**

The **AI Engineering from Scratch** repository (`rohitg00/ai-engineering-from-scratch`) teaches you to build every component of an AI system through hands-on lessons. Introduced in Phase 14, the **Agent Workbench** bridges the gap between curriculum exercises and production codebases, allowing you to deploy autonomous agents into real repositories with full version control and auditability. This guide shows you how to scaffold the workbench, run agent loops, and verify system health using the actual source files from the curriculum.

## What Is the Agent Workbench?

The Agent Workbench is a **version-controlled surface** consisting of three core files that an autonomous agent can read, write, and verify without risking repository corruption. Unlike monolithic agent frameworks, this minimal design treats the agent as a stateful service that persists memory and task queues directly in the filesystem, making every operation reviewable via standard Git workflows.

### Core Components

The workbench relies on three canonical files located in the `.workbench/` directory:

- **[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)** – A declarative router that defines **allowed actions** and **constraints**. It serves as the single source of truth for the agent’s instruction set and security policies.
- **[`agent_state.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/agent_state.json)** – A durable JSON store that persists the agent’s **memory, variables, and intermediate results** across execution runs.
- **[`task_board.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/task_board.json)** – A JSON task backlog that the agent reads to determine **what to work on next**, and writes to signal task completion or failure.

### Schema Validation and Versioning

To prevent corruption, the workbench includes a `schemas/` directory containing JSON-Schema definitions for the three core files. These schemas enable **runtime validation** of any write operation the agent attempts. Version tracking is handled via a `.workbench-version` marker file written by the installer, ensuring idempotent deployments and preventing accidental overwrites of existing state.

## How to Scaffold the Workbench into Any Repository

The curriculum provides two methods for installing the workbench: direct scaffolding from source or installing a pre-built distribution pack.

### Method 1: Direct Scaffolding with [`scaffold_workbench.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scaffold_workbench.py)

The [`scripts/scaffold_workbench.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold_workbench.py) script generates the three core files and writes the installer. Run it from the curriculum root against your target repository:

```bash
python3 scripts/scaffold_workbench.py ./my-target-repo

```

This creates [`.workbench/AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.workbench/AGENTS.md), [`.workbench/agent_state.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.workbench/agent_state.json), and [`.workbench/task_board.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.workbench/task_board.json) inside your target directory, along with the `.workbench-version` marker.

### Method 2: Installing the Distribution Pack

If you have built the pack from the capstone lesson (`phases/14-agent-engineering/42-agent-workbench-capstone/`), use the included installer:

```bash
tar -xzf outputs/agent-workbench-pack.tar.gz -C /tmp/pack
/tmp/pack/agent-workbench-pack/bin/install.sh /path/to/your/repo

```

The installer at [`bin/install.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/bin/install.sh) checks the pack’s `VERSION` file against any existing `.workbench-version` and refuses to overwrite unless you supply the `--force` flag.

## Running Autonomous Tasks with the Workbench

Once installed, the workbench provides a standardized interface for agent loops. Below is a complete implementation that reads the task board, executes commands, and persists state.

### The Agent Loop Implementation

```python

# my-agent.py

import json
import pathlib
import subprocess

WORKBENCH = pathlib.Path("./.workbench")
AGENTS_MD = WORKBENCH / "AGENTS.md"
STATE = json.load(open(WORKBENCH / "agent_state.json"))
BOARD = json.load(open(WORKBENCH / "task_board.json"))

def run_task(task):
    # Execute tool defined in AGENTS.md

    result = subprocess.check_output(["python3", "tools/execute.py", task["command"]])
    return result.decode()

for task in BOARD["tasks"]:
    if task["status"] == "todo":
        output = run_task(task)
        # Update state (validated by schema at write time)

        STATE["last_result"] = output
        task["status"] = "done"
        break

# Persist changes

json.dump(STATE, open(WORKBENCH / "agent_state.json", "w"), indent=2)
json.dump(BOARD, open(WORKBENCH / "task_board.json", "w"), indent=2)

```

Running `python3 my-agent.py` performs three operations: it loads the **task board** to find the next job, executes the job according to the constraints in **AGENTS.md**, and writes the result back to **agent_state.json**. Because these files are standard JSON, you can review every change using `git diff .workbench/` and roll back if the agent produces incorrect results.

## Verifying Workbench Health

The curriculum ships with a **workbench audit skill** that validates the seven critical surfaces of the installation. Invoke it via the SkillKit CLI:

```bash
skillkit run workbench-audit --repo /path/to/your/repo

```

The audit reports on the router (AGENTS.md), state file, task board, schemas, installer, version marker, and verification gates, identifying any missing or malformed components before you deploy an agent.

## Summary

- The **Agent Workbench** consists of three files ([`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), [`agent_state.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/agent_state.json), [`task_board.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/task_board.json)) that provide a safe, version-controlled interface for autonomous agents.
- Use **[`scripts/scaffold_workbench.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold_workbench.py)** to generate a fresh workbench in any repository, or install a versioned pack via **[`bin/install.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/bin/install.sh)**.
- The workbench enforces **JSON-Schema validation** on all writes and tracks versions via `.workbench-version` to prevent state corruption.
- Run agent loops by reading [`task_board.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/task_board.json) for work items and writing results to [`agent_state.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/agent_state.json), with all changes visible in Git diffs.
- Validate installations using the **`workbench-audit`** skill to ensure all seven system surfaces are healthy before production use.

## Frequently Asked Questions

### What is the difference between scaffolding and using the distribution pack?

**Scaffolding** via [`scripts/scaffold_workbench.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold_workbench.py) generates the three core files directly from the curriculum source, ideal for development or customizing the router logic. The **distribution pack** (`outputs/agent-workbench-pack/`) is a versioned artifact created in the capstone lesson that includes the installer, schemas, and version markers, making it suitable for shipping to production repositories or sharing as a SkillKit skill.

### How does the workbench prevent an agent from corrupting my repository?

The workbench isolates the agent’s write surface to three specific JSON files and one markdown file, all contained within the `.workbench/` directory. The **JSON-Schema definitions** in `schemas/` enforce structural constraints on every write. Additionally, [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) acts as a declarative policy layer that restricts which external tools the agent may invoke, creating a sandboxed execution environment.

### Can I run multiple agents on the same repository using this workbench?

Yes, but you must coordinate access to [`agent_state.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/agent_state.json) and [`task_board.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/task_board.json). The curriculum recommends implementing a file-locking mechanism or using atomic writes (write to temp file, then rename) to prevent race conditions. Alternatively, you can instantiate multiple `.workbench/` directories with unique names (e.g., `.workbench-agent-1/`) by modifying the scaffold script’s target path parameter.

### Where can I find the complete source code for the workbench lessons?

The workbench implementation spans two lessons in Phase 14: **Lesson 41** (`phases/14-agent-engineering/41-workbench-for-real-repos/`) covers the theory and scaffolding, while **Lesson 42** (`phases/14-agent-engineering/42-agent-workbench-capstone/`) contains the pack assembly code in [`code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.py). The top-level [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) in the repository root serves as the canonical reference for the router specification.