Agent Workspace Specification

The Agent Workspace Model defines a standard pattern for turning any Git repository into a persistent, context-aware AI workspace. This page documents the complete specification — the folder structure, conventions, and components that make it work.

Reference Repository: The full specification, validation schema, and examples live in the Claude Agent Workspace Model repo.

Point Claude at that repo and tell it to scaffold a workspace for your use case — it will generate the full structure automatically.

Lifecycle Stages

Every workspace moves through three stages:

1. Scaffold Clone template, get the structure

2. Personalize Run /onboard, ingest context

3. Ready Fully configured, start working

The cloned template comes pre-populated with the structural mechanics (folders, CLAUDE.md, slash commands, MCP config) but is a blank page in terms of context. The /onboard command drives the Personalize stage.

Required Directory Structure

Every Agent Workspace must contain these directories and a root CLAUDE.md:

my-workspace/ ├── CLAUDE.md # Agent instructions (keep lightweight) ├── context/ # User-provided context and agent reference │ ├── project.md # Project name, description, goals │ ├── role.md # User's role and how it shapes the work │ ├── constraints.md # Boundaries, deadlines, preferences │ └── for-agent/ # Detailed instructions for the agent │ ├── environment.md # OS, tools, paths │ ├── workflows.md # Step-by-step workflow instructions │ └── ... ├── work-log/ # Daily operation logs (YYYY-MM-DD.md) ├── planning/ # Active plan + pivot records │ ├── plan.md # Current active plan │ └── pivots/ # Plan change records ├── user-docs/ # Agent-produced deliverables for the user ├── .claude/ │ └── commands/ # Slash commands │ └── onboard.md # Required: initializes the workspace └── .mcp.json # Optional: MCP server configurations

Component Reference

CLAUDE.md — The Agent's Instruction File

This file is loaded with every prompt, so it must be kept lightweight. It should contain only:

What this workspace is and what template it was created from
The agent's role (one sentence)
A list of available slash commands
Stubs pointing to detailed context files

Detailed instructions, environment specifics, and domain knowledge belong in context/for-agent/, not in CLAUDE.md.

context/ — The Knowledge Base

Path	Purpose	Created By
`project.md`	Project name, description, goals	`/onboard`
`role.md`	User's role and how it shapes the work	`/onboard`
`constraints.md`	Boundaries, deadlines, preferences	`/onboard`
`for-agent/environment.md`	User's environment details (OS, tools, paths)	`/onboard`
`for-agent/workflows.md`	Detailed workflow instructions for the agent	Template or `/onboard`
`for-agent/*.md`	Any detailed agent instructions too verbose for CLAUDE.md	Template, user, or agent

Key principle: CLAUDE.md contains stubs; context/for-agent/ contains substance.

work-log/ — Operational History

The agent creates a new entry for each day it operates. Each file is named YYYY-MM-DD.md.

planning/ — Plans and Pivots

There is always exactly one plan.md representing the current state. When the plan changes significantly, the agent records the pivot in pivots/.

user-docs/ — Deliverables

Polished, user-facing documents: research summaries, decision frameworks, reference guides.

The Four-Layer Stack

1 Context Layer

CLAUDE.md + context/ directory + working files.

2 Command Layer

Slash commands (.claude/commands/), shell scripts, context aliases.

3 Integration Layer

MCP servers, external APIs, CLI tools. Configured via .mcp.json.

4 Execution Layer

File operations, shell commands, tool calls.

Validation Checklist

CLAUDE.md exists at root
context/ directory exists
work-log/ directory exists
planning/ directory exists
user-docs/ directory exists
.claude/commands/onboard.md exists
If context/project.md does not exist, prompt user to run /onboard

View Full Specification Browse Agent Workspaces →