# Designing an Agent Workbench for AI Development: A Three-File Minimal Framework

> Design an AI agent workbench for durable state persistence and task management using three core files. Learn to build a minimal framework for robust AI development.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: architecture
- Published: 2026-07-19

---

**An agent workbench provides durable state persistence and task management through three core 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), and [`task_board.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/task_board.json)—enabling AI agents to maintain context across sessions without relying on volatile chat history.**

Designing an agent workbench for AI development requires solving the fundamental problem of state persistence across sessions. The `rohitg00/ai-engineering-from-scratch` repository implements a lightweight, file-based framework that eliminates the single point of failure represented by chat history. This approach gives AI agents a durable place to store state, a clear task queue, and a concise routing file, allowing models to focus on problem-solving rather than re-learning coordination patterns.

## Core Architecture of the Agent Workbench

The minimal viable workbench consists of exactly three files that abstract repetitive scaffolding. According to the source code in `phases/14-agent-engineering/32-minimal-agent-workbench/`, these files work together to create a durable system of record.

### The Router File (AGENTS.md)

**[`workdir/AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/workdir/AGENTS.md)** serves as a short router that points the agent to the state file, task board, and deeper rule documentation. It replaces massive, monolithic manuals and keeps the model’s context budget low by only loading deeper docs when needed.

### The State File (agent_state.json)

**[`workdir/agent_state.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/workdir/agent_state.json)** acts as the system of record, implemented via the `AgentState` dataclass. It holds the current active task ID, files touched during the turn, assumptions, blockers, and the next action the agent should take. This persists across sessions, eliminating reliance on volatile chat history.

### The Task Board (task_board.json)

**[`workdir/task_board.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/workdir/task_board.json)** maintains a JSON queue of tasks with fields `id`, `goal`, `owner`, `acceptance`, and `status`. The agent pulls the next `todo` task when the state is empty, providing a persistent view of work progress that survives process restarts.

## How the Agent Workbench Works

The reference implementation in [`phases/14-agent-engineering/32-minimal-agent-workbench/code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/32-minimal-agent-workbench/code/main.py) demonstrates a deterministic five-step lifecycle:

1. **Bootstrap** – The script creates the three files if they don’t exist using `write_initial(state_path, board_path, agents_path)`.
2. **Load** – At the start of each turn, the agent reads the current context via `load_state(state_path)` and `load_board(board_path)`.
3. **Decision** – If no active task exists, the agent picks the next `todo` task, marks it `in_progress`, and records the task ID in the state. If an active task exists, the agent performs deterministic actions: touching source files, adding tests, running verification, then marking the task `done`.
4. **Persist** – Updated state and board are written back to disk using `save_state(state_path, state)` and `save_board(board_path, board)`.
5. **Repeat** – Re-running the script demonstrates continuity across sessions as the second turn automatically picks up where the first left off.

## Why Three Files?

The three-file constraint in `rohitg00/ai-engineering-from-scratch` provides specific architectural advantages:

- **Simplicity** – Anything more complex builds on this foundation, making it easy to reason about, test, and version-control.
- **Portability** – The same three files map directly onto conventions of major AI coding assistants (Claude Code, Cursor, Codex) with only naming tweaks.
- **Reliability** – By storing the workbench on disk, you remove the single point of failure that chat history represents. The workbench can be audited, linted, and migrated independently of the model.

## Extending the Workbench

Later lessons in Phase 14 demonstrate how to layer additional surfaces on top of the base three files. According to [`phases/14-agent-engineering/34-repo-memory-and-state/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/34-repo-memory-and-state/docs/en.md), extensions include:

- **Scope contracts** – Defining which files the agent may modify
- **Verification gates** – Commands that confirm a task’s definition of done
- **Reviewer agents** – Automatic checks before a task is marked `done`
- **Handoff packets** – Machine-readable summaries for the next session

All extensions read and write the same three core files, preserving backward compatibility while adding robustness.

## Implementation Example

The following example from [`code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.py) demonstrates the workbench scaffold and a single agent turn:

```python

# Run the workbench scaffold and one agent turn

python3 code/main.py

```

The script performs these specific operations:

```python

# 1. Ensure the workdir exists

ROOT.mkdir(exist_ok=True)

# 2. Write AGENTS.md, agent_state.json, and task_board.json if missing

write_initial(state_path, board_path, agents_path)

# 3. Load the current state and task board

state = load_state(state_path)
board = load_board(board_path)

# 4. Print the pre-turn status

print("before turn:", state.active_task_id, state.next_action)

# 5. Run a deterministic turn

state, board = run_one_turn(state, board)

# 6. Persist the updated files

save_state(state_path, state)
save_board(board_path, board)

# 7. Print the post-turn status

print("after turn:", state.active_task_id, state.next_action)

```

Running the script a second time will show the agent picking up the next task automatically, proving the durability of the workbench architecture.

## Summary

- **Designing an agent workbench for AI development** requires only three files: [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) for routing, [`agent_state.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/agent_state.json) for durable context, and [`task_board.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/task_board.json) for task queue management.
- The `AgentState` dataclass in [`agent_state.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/agent_state.json) tracks active task IDs, touched files, assumptions, and next actions across sessions.
- Functions `load_state()`, `save_state()`, `load_board()`, and `save_board()` provide the persistence layer that eliminates dependency on chat history.
- The three-file approach balances simplicity with extensibility, allowing later phases to add scope contracts and verification gates without breaking the core schema.
- This architecture is implemented in [`phases/14-agent-engineering/32-minimal-agent-workbench/code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/32-minimal-agent-workbench/code/main.py) in the `rohitg00/ai-engineering-from-scratch` repository.

## Frequently Asked Questions

### What makes the three-file workbench architecture reliable for AI development?

The three-file architecture eliminates the single point of failure represented by volatile chat history. By storing state in [`agent_state.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/agent_state.json) and the task queue in [`task_board.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/task_board.json) on disk, the workbench survives process restarts, CI runs, and human hand-offs. Files can be version-controlled, audited, and migrated independently of the model, providing deterministic continuity across sessions.

### How does the AGENTS.md file reduce context usage?

[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) acts as a lightweight router rather than a comprehensive manual. It points the agent to the state file, task board, and deeper rule documentation only when needed. This concision keeps the model’s context budget focused on the actual problem rather than coordination mechanics, which is critical when designing an agent workbench for AI development with limited token windows.

### Can the minimal workbench handle complex multi-step workflows?

Yes. The [`task_board.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/task_board.json) queue supports complex workflows through its `id`, `goal`, `owner`, `acceptance`, and `status` fields. The `run_one_turn()` function in [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) demonstrates how agents perform deterministic actions—touching files, adding tests, running verification—before marking tasks `done`. Later lessons in Phase 14 show how to add verification gates and reviewer agents without changing the core three-file structure.

### Where can I find the reference implementation for this agent workbench?

The complete reference implementation is located in [`phases/14-agent-engineering/32-minimal-agent-workbench/code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/32-minimal-agent-workbench/code/main.py) within the `rohitg00/ai-engineering-from-scratch` repository. The accompanying documentation in [`phases/14-agent-engineering/32-minimal-agent-workbench/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/32-minimal-agent-workbench/docs/en.md) explains the three-file concept in depth, while [`phases/14-agent-engineering/34-repo-memory-and-state/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/34-repo-memory-and-state/docs/en.md) covers extending the workbench into a full repository memory system.