# How the Agent Workbench Functions in Phase 14: A Complete Technical Guide

> Discover how the agent workbench functions in Phase 14. This technical guide explains how it creates a reproducible environment for seamless AI agent session handoffs, persisting state, task boards, schemas, and constraints.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: deep-dive
- Published: 2026-06-17

---

**The agent workbench in Phase 14 creates a reproducible, verifiable environment by persisting seven canonical surfaces—state, task boards, schemas, and executable constraints—enabling seamless handoffs between AI agent sessions.**

In the `rohitg00/ai-engineering-from-scratch` repository, Phase 14 (Agent Engineering) introduces a durable framework that transforms fleeting agent interactions into persistent, auditable workflows. The agent workbench functions as the backbone of this system, providing the infrastructure needed for reliable, production-grade AI agents through structured data surfaces and validation mechanisms.

## The Seven Canonical Surfaces of the Agent Workbench

The workbench captures everything an agent needs to continue sessions, undergo review, and hand off to future iterations across seven distinct surfaces:

- **Instructions** ([`workdir/AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/workdir/AGENTS.md)): A router file that points the agent to other surfaces and states high-level constraints.
- **State** ([`workdir/agent_state.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/workdir/agent_state.json)): A JSON snapshot of the current task, files touched, blockers, assumptions, and next actions.
- **Task Board** ([`workdir/task_board.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/workdir/task_board.json)): A JSON list of tasks with `id`, `goal`, `owner`, `acceptance` commands, and status (`todo` / `in_progress` / `done`).
- **Docs** ([`docs/agent-rules.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/agent-rules.md)): Human-readable rules written as executable constraints that the agent evaluates at runtime.
- **Schemas** (`schemas/*.schema.json`): JSON-Schema definitions for state and task-board validation, ensuring shape compatibility across versions.
- **Scripts** (`scripts/`, `bin/`): Helper scripts for installation, validation, and migration, such as [`bin/install.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/bin/install.sh) and [`scripts/verify_agent.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/verify_agent.py).
- **Handoff** (`outputs/agent-workbench-pack/`): Bundled packages containing all surfaces plus a one-command installer for distribution to other repositories.

## Step-by-Step Workbench Lifecycle

### Bootstrap (Lesson 32)

The minimal workbench is created in Lesson 32. The script at [`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) initializes 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).

```python

# Simplified view from main.py

ROOT = Path(__file__).parent / "workdir"
AGENTS_MD = """# AGENTS.md

This repo runs with a workbench. Read these before acting:
1. `agent_state.json`
2. `task_board.json`
3. `docs/agent-rules.md`
"""

# write_initial() writes the three files if they don't exist.

```

Running this script once produces a persistent `workdir/` directory that survives across sessions.

### Persist and Load Cycle

Every turn, the agent loads the JSON state and board, executes logic, and persists changes back to disk. This cycle in [`phases/14-agent-engineering/34-repo-memory-and-state/code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/34-repo-memory-and-state/code/main.py) ensures no data is lost between runs.

```python
state = load_state(state_path)           # → AgentState dataclass

board = load_board(board_path)           # → list[Task]

state, board = run_one_turn(state, board)  # core loop

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

```

### Executable Constraints (Lesson 33)

The workbench treats instructions as runtime checks. The [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) router points to [`docs/agent-rules.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/agent-rules.md), which contains test-style constraints (e.g., "`assert task.status == 'done'`"). These rules are parsed and evaluated during execution, turning static documentation into active validation logic.

### Scope Contracts and Schema Validation (Lesson 36)

JSON-Schema files ([`schemas/agent_state.schema.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/schemas/agent_state.schema.json), [`schemas/task_board.schema.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/schemas/task_board.schema.json)) define strict contracts for data shapes. When the workbench version changes, migration scripts validate compatibility, preventing silent corruption of agent state. This is implemented in [`phases/14-agent-engineering/36-scope-contracts/code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/36-scope-contracts/code/main.py).

### Initialization Scripts (Lesson 35)

Fresh repository clones can bootstrap the workbench immediately using [`scripts/init_agent.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/init_agent.py). The installer at [`bin/install.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/bin/install.sh) creates a `.workbench-version` file to lock the workbench version, ensuring consistency across environments.

### Verification Gates (Lesson 38)

Before marking tasks complete, the workbench executes acceptance commands defined in the task board. Located in [`phases/14-agent-engineering/38-verification-gates/code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/38-verification-gates/code/main.py), this system runs commands like `python -m pytest -x` and records outcomes, creating an auditable trail of agent decisions.

### Multi-Session Handoff (Lesson 40)

The workbench exports handoff packets via [`phases/14-agent-engineering/40-multi-session-handoff/code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/40-multi-session-handoff/code/main.py), generating [`outputs/hand-off.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/outputs/hand-off.json) and markdown summaries. These packets contain the final `agent_state`, `task_board`, and artifacts, enabling downstream reviewers or new agents to resume work seamlessly.

### Pack and Install (Lesson 42)

The capstone lesson assembles a drop-in pack at `outputs/agent-workbench-pack/`. This includes all seven surfaces, schema files, and a unified installer:

```bash
./bin/install.sh /path/to/target-repo   # writes .workbench-version, copies files

```

The pack integrates with SkillKit (`skillkit install agent-workbench-pack`) and supports the curriculum's 32 agents.

## Running a Turn in the Agent Workbench

To observe the workbench in action, execute the minimal implementation:

```bash
python3 phases/14-agent-engineering/32-minimal-agent-workbench/code/main.py

```

Output:

```

before turn:
  active task : None
  next action : 'pick work on T-001: add input validation to /signup'
  todo on board: ['T-001', 'T-002']

after turn:
  active task : T-001
  touched     : ['app.py']
  next action : 'add test for T-001 acceptance'
  board status: [('T-001', 'in_progress'), ('T-002', 'todo')]

```

Subsequent runs load the persisted [`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), continuing exactly where the previous session ended.

## Summary

- The agent workbench in Phase 14 provides seven canonical surfaces that capture instructions, state, tasks, documentation, schemas, scripts, and handoff packages.
- State persistence occurs through JSON files ([`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 are loaded and saved every turn via functions like `load_state()` and `save_board()`.
- Executable constraints in [`docs/agent-rules.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/agent-rules.md) function as runtime validation, ensuring agents adhere to defined rules.
- JSON-Schema definitions in `schemas/*.schema.json` enforce data integrity and support version migration.
- Verification gates execute acceptance commands from the task board before marking work complete.
- The capstone delivers a distributable pack with [`bin/install.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/bin/install.sh) for one-command deployment to any repository.

## Frequently Asked Questions

### What files make up the minimal agent workbench in Phase 14?

The minimal workbench consists of three files created by [`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): [`workdir/AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/workdir/AGENTS.md) (the instruction router), [`workdir/agent_state.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/workdir/agent_state.json) (session state), and [`workdir/task_board.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/workdir/task_board.json) (task tracking). These files enable basic persistence and handoff capabilities.

### How does the agent workbench ensure data integrity across versions?

The workbench uses JSON-Schema definitions located in [`schemas/agent_state.schema.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/schemas/agent_state.schema.json) and [`schemas/task_board.schema.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/schemas/task_board.schema.json) to validate data shapes. When versions change, migration scripts verify schema compatibility, preventing silent corruption and ensuring that persisted state remains valid.

### Can the agent workbench be transferred between different repositories?

Yes. Lesson 42 packages the workbench into `outputs/agent-workbench-pack/`, which includes all seven surfaces and an installer script. Running `./bin/install.sh /path/to/target-repo` copies the files and writes a `.workbench-version` marker, enabling immediate use in new environments via SkillKit or manual installation.

### How are tasks validated before completion in the workbench?

The verification gates system in [`phases/14-agent-engineering/38-verification-gates/code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/38-verification-gates/code/main.py) executes acceptance commands defined in the task board's `acceptance` field (such as `python -m pytest -x`). The workbench records the exit codes and output, ensuring only verified tasks are marked `done` and creating an auditable record of agent progress.