# Building Agent Workbench Systems with Scope Contracts: A Complete Guide to AI-Engineering-From-Scratch

> Master AI engineering from scratch! Build robust agent workbench systems with scope contracts using the rohitg00/ai-engineering-from-scratch repository. Get the essential guide now.

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

---

**The rohitg00/ai-engineering-from-scratch repository implements a deterministic agent workbench architecture using 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)—governed by executable scope contracts that enforce operational boundaries through rule-checking scripts and CI-integrated verification gates.**

The *AI-Engineering-From-Scratch* curriculum provides a production-grade framework for constructing reliable AI-agent workbenches from first principles. Spanning 20 phases and over 400 lessons, this educational codebase teaches how to build autonomous systems using pure-standard-library implementations in Python, TypeScript, Rust, and Julia. Building agent workbench systems with scope contracts ensures that autonomous agents operate within deterministic, machine-readable boundaries while maintaining durable state across interrupted development cycles.

## Core Components of the Minimal Agent Workbench

The foundation of the system rests on a **minimal workbench**—a durable set of artifacts that persist between agent sessions. According to [`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), every workbench requires exactly three files in the repository root.

### The Three-File Foundation

- **[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)**: The root router that directs the agent to state files, task boards, and rule documentation.
- **[`agent_state.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/agent_state.json)**: Persistent state storage containing the active task, session history, and metadata.
- **[`task_board.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/task_board.json)**: A structured backlog of tasks with status fields (`todo`, `in_progress`, `done`).

These files form the "floor" on which all higher-level surfaces are built. The curriculum emphasizes that these artifacts must be machine-readable to enable deterministic agent behavior across multiple sessions.

### Scaffold Initialization

To initialize a new workbench, the repository provides [`scripts/scaffold_workbench.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold_workbench.py). This utility generates the three core files and seeds an initial backlog:

```python
from scripts.scaffold_workbench import scaffold

scaffold(
    target_dir=".",
    backlog=[{"id": "t1", "goal": "Add README", "owner": "builder"}]
)

```

Running this script creates the foundational structure required for any agent workbench system.

## Defining and Enforcing Scope Contracts

**Scope contracts** express the boundaries of a workbench—specifying which files, directories, and operational rules are relevant to the agent. As documented in [`phases/14-agent-engineering/33-instructions-as-executable-constraints/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/33-instructions-as-executable-constraints/docs/en.md), these contracts transform prose instructions into executable constraints.

### Instructions as Executable Constraints

The contract system encodes operational rules in [`docs/agent-rules.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/agent-rules.md). Each rule includes a `check` field that maps to a deterministic Python function in [`rule_checker.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/rule_checker.py). For example, a rule might specify that agents may only modify files within the `src/` directory, with the checker function returning a boolean verdict.

This approach ensures that **scope contracts** are not merely documentation but actively enforced code that prevents boundary violations.

### Verification Gates in CI

**Verification gates** are deterministic functions that read workbench artifacts and produce a pass/fail verdict. Located in [`phases/14-agent-engineering/38-verification-gates/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/38-verification-gates/docs/en.md), these gates are version-controlled Python scripts (e.g., [`gate.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/gate.py)) wired directly into CI pipelines.

```python

# Example verification gate structure

def verify_scope_compliance():
    state = json.loads(Path("agent_state.json").read_text())
    touched_files = state.get("touched_files", [])
    return all(f.startswith("src/") for f in touched_files)

```

If a gate returns `false`, the CI pipeline fails, preventing agents from bypassing quality checks or violating scope constraints.

## Multi-Session State Management and Handoff

A critical challenge in agent workbench systems is maintaining continuity across interrupted sessions. The repository solves this through **multi-session handoff** protocols and **runtime feedback loops**.

### The Handoff Packet

At the end of each session, the workbench emits [`handoff.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/handoff.md) and [`handoff.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/handoff.json) containing seven canonical fields that the next session immediately consumes. As specified in [`phases/14-agent-engineering/40-multi-session-handoff/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/40-multi-session-handoff/docs/en.md), these files encapsulate the complete state required for seamless continuation.

```python
from pathlib import Path
import json

def generate_handoff():
    handoff = {
        "state": json.loads(Path("agent_state.json").read_text()),
        "board": json.loads(Path("task_board.json").read_text()),
        "artifacts": {"touched_files": ["src/module.py"]},
        "metadata": {"version": "1.0.0"},
    }
    Path("handoff.json").write_text(json.dumps(handoff, indent=2))
    Path("handoff.md").write_text(f"# Handoff Summary\n\nSee `handoff.json` for details.")

```

This deterministic packet ensures that no context is lost between agent turns.

### Runtime Feedback Loops

The workbench records execution metadata—duration, error codes, and completion status—in a JSONL log file. The [`run_with_feedback.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/run_with_feedback.py) script appends entries after each agent turn, enabling the next iteration to adapt behavior based on historical performance data. This feedback mechanism creates a self-correcting system where agents learn from previous session outcomes.

## Executing Agent Turns Within Scope

An agent turn follows a strict lifecycle governed by the workbench artifacts. The agent reads its last known state, pulls the next task from the board, executes within defined scope constraints, and writes updated state.

```python
import json
import pathlib

state_path = pathlib.Path("agent_state.json")
board_path = pathlib.Path("task_board.json")

# Read current state

state = json.loads(state_path.read_text())

if not state.get("active_task"):
    # Pull next TODO from board

    board = json.loads(board_path.read_text())
    todo = next(t for t in board if t["status"] == "todo")
    state["active_task"] = todo["id"]
    todo["status"] = "in_progress"

# Execute task within scope

task_id = state["active_task"]
pathlib.Path(f"src/{task_id}.py").write_text("# generated\n")

state["last_modified"] = task_id

# Persist state

state_path.write_text(json.dumps(state, indent=2))

```

This pattern ensures that every file modification occurs within the boundaries defined by the **scope contract**, with state changes atomically committed to [`agent_state.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/agent_state.json).

## Packaging and Distribution

The curriculum culminates in [`phases/14-agent-engineering/42-agent-workbench-capstone/outputs/agent-workbench-pack/README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/42-agent-workbench-capstone/outputs/agent-workbench-pack/README.md), which bundles all workbench surfaces into a distributable package.

### The Workbench Pack

The final capstone lesson generates an `agent-workbench-pack` directory containing:

- All core workbench files ([`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), state schemas, rule sets)
- An installer script at [`bin/install.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/bin/install.sh)
- A version file `.workbench-version` for compatibility checking

Install the packaged workbench into any target repository using:

```bash
bash bin/install.sh --target /path/to/other/repo

```

The installer writes `.workbench-version` to enforce version compatibility on subsequent deployments, ensuring that distributed workbenches maintain consistent **scope contracts** across different codebases.

## Summary

- **Agent workbench systems** require three core files: [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (router), [`agent_state.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/agent_state.json) (persistence), and [`task_board.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/task_board.json) (backlog).
- **Scope contracts** are enforced through executable rule-checking scripts that map constraints to deterministic Python functions.
- **Verification gates** provide CI-integrated pass/fail checks that prevent agents from violating operational boundaries.
- **Multi-session handoff** uses [`handoff.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/handoff.json) and [`handoff.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/handoff.md) with seven canonical fields to maintain state across interrupted development cycles.
- **Runtime feedback loops** record execution data in JSONL logs, enabling adaptive behavior in subsequent agent turns.
- The **workbench pack** system ([`bin/install.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/bin/install.sh)) enables drop-in deployment of scoped agent environments into any repository.

## Frequently Asked Questions

### What are the three essential files in a minimal agent workbench?

According to [`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), every minimal workbench requires [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (the router), [`agent_state.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/agent_state.json) (persistent state), and [`task_board.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/task_board.json) (task backlog). These three files form the "floor" that supports all higher-level agent operations and multi-session persistence.

### How do scope contracts prevent unauthorized file modifications?

**Scope contracts** encode operational boundaries in [`docs/agent-rules.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/agent-rules.md), with each rule mapping to a deterministic check function in [`rule_checker.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/rule_checker.py). These rules are enforced by **verification gates**—deterministic functions wired into CI that return `false` if an agent attempts to modify files outside allowed directories (such as `src/`), immediately failing the build and blocking the violation.

### What data is included in a multi-session handoff packet?

The handoff packet, generated as [`handoff.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/handoff.json) and [`handoff.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/handoff.md), contains seven canonical fields including the complete `state` object, current `board` status, lists of `artifacts` (touched files), and `metadata` (version info). This structure is documented in [`phases/14-agent-engineering/40-multi-session-handoff/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/40-multi-session-handoff/docs/en.md) and ensures zero-context-loss between agent sessions.

### How does the scaffold script initialize a new workbench?

The [`scripts/scaffold_workbench.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold_workbench.py) utility generates the three core files and seeds an initial backlog when invoked with `scaffold(target_dir=".", backlog=[...])`. This creates the foundational [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) router, empty state files, and a populated task board, preparing the repository for deterministic agent operation within defined scope constraints.