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

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): A router file that points the agent to other surfaces and states high-level constraints.
• State (workdir/agent_state.json): A JSON snapshot of the current task, files touched, blockers, assumptions, and next actions.
• Task Board (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): 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 and 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 initializes three core files: AGENTS.md, agent_state.json, and task_board.json.

# 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 ensures no data is lost between runs.

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 router points to 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, 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.

Initialization Scripts (Lesson 35)

Fresh repository clones can bootstrap the workbench immediately using scripts/init_agent.py. The installer at 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, 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, generating 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:

./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:

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 and 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, 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 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 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: workdir/AGENTS.md (the instruction router), workdir/agent_state.json (session state), and 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 and 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}