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

The rohitg00/ai-engineering-from-scratch repository implements a deterministic agent workbench architecture using three core files—AGENTS.md, agent_state.json, and 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, every workbench requires exactly three files in the repository root.

The Three-File Foundation

• AGENTS.md: The root router that directs the agent to state files, task boards, and rule documentation.
• agent_state.json: Persistent state storage containing the active task, session history, and metadata.
• 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. This utility generates the three core files and seeds an initial backlog:

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, these contracts transform prose instructions into executable constraints.

Instructions as Executable Constraints

The contract system encodes operational rules in docs/agent-rules.md. Each rule includes a check field that maps to a deterministic Python function in 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, these gates are version-controlled Python scripts (e.g., gate.py) wired directly into CI pipelines.

# 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 and 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, these files encapsulate the complete state required for seamless continuation.

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

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.

Packaging and Distribution

The curriculum culminates in 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, state schemas, rule sets)
• An installer script at bin/install.sh
• A version file .workbench-version for compatibility checking

Install the packaged workbench into any target repository using:

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 (router), agent_state.json (persistence), and 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 and 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) 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, every minimal workbench requires AGENTS.md (the router), agent_state.json (persistent state), and 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, with each rule mapping to a deterministic check function in 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 and 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 and ensures zero-context-loss between agent sessions.

How does the scaffold script initialize a new workbench?

The 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 router, empty state files, and a populated task board, preparing the repository for deterministic agent operation within defined scope constraints.

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