Model Workspace Protocol (MWP)

• MWP is a filesystem-based protocol for structuring and executing sequential AI workflows using hierarchical folders, markdown context files, and scripts.
• It organizes workflow state into a five-layer context model, enabling precise control over token usage and intermediate artifacts between stages.
• The protocol emphasizes human review at each step, allowing for easy edits and versioning akin to 'infrastructure as code' for AI applications.

Model Workspace Protocol (MWP) is a filesystem-based protocol for orchestrating multi-step AI work. Instead of implementing orchestration logic in a multi-agent framework, it uses a folder hierarchy, numbered stage directories, markdown context files, and local scripts to control how a model moves through a workflow. Its intended problem is specific: sequential workflows where a human reviews output at each step. Within that scope, MWP treats the filesystem as the orchestration layer and the workspace as the carrier of context, state, and intermediate artifacts (Clief et al., 17 Mar 2026).

1. Definition and scope

MWP is not presented as “an agent framework” in the usual sense. It is a protocol for structuring context delivery and workflow state through the filesystem. In the canonical description, one orchestrating model progresses through a workspace; it is not permanently assigned a fixed role such as “research agent” or “writer agent,” but instead becomes those roles by reading different context files at different stages. The same model may delegate subtasks to smaller models, but the protocol does not require a multi-agent architecture. The protocol is open source under the MIT license, and the paper states that the workspaces described there were developed with Claude Code, Claude Opus 4.6 as the primary agent, and Claude Sonnet 4.6 for delegated sub-agent tasks, while remaining model-agnostic at the protocol level (Clief et al., 17 Mar 2026).

The protocol’s scope is deliberately narrow. It is proposed as an alternative to code-heavy orchestration frameworks such as CrewAI, LangChain, and AutoGen for workflows that are sequential, human-reviewed after each step, repeatable, and often modified by changing prompts, order, or stages. In that setting, the control surface is relocated from orchestration code into visible file structure: change stage order by renaming or reordering folders, modify a prompt by editing markdown, add or remove a stage by adding or deleting a folder, inspect state by opening the folder, and hand off to another person by copying the folder (Clief et al., 17 Mar 2026).

The acronym is ambiguous outside this usage. In "MWP-BERT: Numeracy-Augmented Pre-training for Math Word Problem Solving" (Liang et al., 2021), MWP denotes math word problem solving, and in "mwp-Analysis Improvement and Implementation: Realizing Implicit Computational Complexity" (Aubert et al., 2022), mwp denotes mwp-flow or mwp-bounds static analysis. Neither usage refers to Model Workspace Protocol (Liang et al., 2021, Aubert et al., 2022).

2. Workspace architecture and context hierarchy

The canonical MWP layout is a rooted directory whose top level contains identity, routing, shared configuration, and numbered stages. The paper gives the following structure:

workspace/ CLAUDE.md CONTEXT.md stages/ 01_research/ CONTEXT.md references/ output/ 02_script/ CONTEXT.md references/ output/ 03_production/ CONTEXT.md references/ output/ _config/ shared/ setup/ questionnaire.md

Numbered stage folders such as 01_research, 02_script, and 03_production encode execution order. Reordering stages can be done by renaming folders. Folder boundaries enforce separation of concerns: each stage does one job, writes output only to its own folder, and receives input via explicit references in its contract. The output/ directory of one stage becomes the handoff point for the next stage; if a human edits files in 01_research/output/ before stage 2 runs, the next stage uses the edited version (Clief et al., 17 Mar 2026).

A central technical contribution is the five-layer context model, which organizes how context is persisted and loaded. The paper associates Layer 0 with roughly ~800 tokens, Layer 1 with roughly ~300 tokens, Layer 2 with 200–500 tokens per stage file, and Layer 3 with 500–2k tokens depending on stage.

Layer	Canonical artifact	Function
0	CLAUDE.md	Global identity: “Where am I?”
1	Root CONTEXT.md	Workspace routing: “Where do I go?”
2	Stage CONTEXT.md	Stage contract: “What do I do?”
3	references/, _config/, shared/	Stable rules: “What rules apply?”
4	output/ and run-specific inputs	Working material: “What am I working with?”

The distinction between Layers 3 and 4 is semantically central. Layer 3 is reference material: persistent constraints such as style guides, voice guides, design systems, conventions, domain knowledge, and skill files. The model should internalize these as constraints. Layer 4 is working material: source documents, previous stage output, user-provided input, and generated intermediate artifacts. The model should process these as input. The paper summarizes the distinction as “the factory” versus “the product,” and gives the analogy “the recipe” versus “the ingredients” (Clief et al., 17 Mar 2026).

3. Stage contracts and execution semantics

The main execution unit in MWP is the stage contract, stored as CONTEXT.md inside each stage directory. Each contract has three parts: Inputs, Process, and Outputs. The paper’s example is:

## Inputs - Layer 4 (working): ../01_research/output/ - Layer 3 (reference): ../../_config/voice.md - Layer 3 (reference): references/structure.md ## Process Write a script based on the research output. Follow the structure in structure.md. Match the tone described in voice.md. ## Outputs - script_draft.md -> output/

Operationally, a stage proceeds by reading the stage CONTEXT.md, loading exactly the files listed under Inputs, performing the Process instruction, and writing the declared outputs into output/. Layer 2 is therefore the main control point of execution, because the stage contract explicitly scopes what the model should load. The paper notes that the Inputs table can specify which sections of files matter, not just which files (Clief et al., 17 Mar 2026).

The full lifecycle is described as a sequential, stage-based execution pipeline with human review gates. A typical run begins with workspace setup, where stable materials are configured in _config/, shared/, and stage references/, optionally using setup/questionnaire.md. The agent then reads CLAUDE.md and the root CONTEXT.md to orient itself and route to the correct stage. Each numbered stage loads only the declared Layer 3 and Layer 4 inputs, performs its task, and writes outputs into its local output/. A human then inspects the output files, may edit them directly, and may decide to proceed, rerun, revise, or stop. The next stage consumes the approved or modified outputs of the prior stage as Layer 4 working material (Clief et al., 17 Mar 2026).

State is not hidden in memory or an orchestrator object. It is persisted in the filesystem as workspace identity files, contracts, reference documents, and output artifacts. A stage transition is therefore previous stage output/ → human review/edit → next stage Input load. The protocol also separates AI from deterministic work: local Python scripts handle tasks such as fetching data, moving files, formatting output, and sending emails. The paper explicitly states that external service integration can happen via local scripts or MCP connections, but that this is distinct from MWP itself (Clief et al., 17 Mar 2026).

4. Design principles and intellectual lineage

The paper gives five explicit design principles. First, one stage, one job: each stage should handle a single workflow step and write its own output. Second, plain text as the interface: stages communicate through markdown and JSON files. Third, layered context loading: the model loads only what is needed for the current stage. Fourth, every output is an edit surface: intermediate artifacts are meant to be human-editable before the next stage runs. Fifth, configure the factory, not the product: stable preferences, brand, style, and conventions should be set up once and reused across runs (Clief et al., 17 Mar 2026).

The intellectual lineage is unusually explicit. The strongest influence is Unix pipelines: small composable stages, output of one stage as input to the next, and text as a universal interface. The paper also situates MWP in pipe-and-filter architecture, make and build systems, modular decomposition, multi-pass compilation, literate programming, human-centered AI and mixed-initiative design, and Plan 9’s “everything is a file” sensibility. The compiler analogy is especially strong: research output, script output, and production output are treated as intermediate representations processed in successive passes (Clief et al., 17 Mar 2026).

MWP is also justified as a context-engineering strategy. The paper contrasts stage-scoped prompting with monolithic prompting, associating MWP stages with roughly 2,000–8,000 tokens and a monolithic approach with roughly 30,000–50,000+ tokens, with much irrelevant context. This is presented partly as a defense against “lost in the middle” degradation. A plausible implication is that MWP reframes prompt engineering as the design of explicit context surfaces and state transitions rather than the construction of a single large prompt (Clief et al., 17 Mar 2026).

5. Relationship to adjacent protocols and systems

MWP is explicitly distinguished from Anthropic’s Model Context Protocol (MCP). In the paper’s formulation, MCP solves how models connect to tools and services, whereas MWP solves how context and stage structure are organized across a workflow. The two are described as complementary: a stage may use MCP tools, but MWP determines what context that stage loads (Clief et al., 17 Mar 2026).

That positioning places MWP alongside a growing family of workspace-oriented protocols. CHAP, the "Collaborative Human-Agent Protocol," defines a shared human-agent workspace with workspaces, participants, tasks, artefacts, and an append-only evidence log, and presents itself as the missing workspace layer between MCP and A2A for accountable collaboration over time (Shahid et al., 8 Jun 2026). AWCP, the "Agent Workspace Collaboration Protocol," addresses a different but adjacent problem: temporary workspace delegation, in which a Delegator projects a selected directory tree to a remote Executor through a leased session and pluggable transport mechanisms (Nie et al., 24 Feb 2026). AMP or memorywire standardizes a narrow state slice—remember, recall, forget, merge, and expire over four memory types—and is positioned as a vendor-neutral protocol meant to compose with MCP rather than compete with it (Munirathinam, 31 May 2026).

Security and governance are likewise being externalized into neighboring protocol layers. SMCP, the "Secure Model Context Protocol," extends MCP with unified identity, mutual authentication, session-bound security context propagation, fine-grained policy enforcement, and structured audit logging; the paper explicitly frames these concerns as relevant to any MWP-like protocol once shared workspace state, tools, or collaboration artifacts cross trust boundaries (Hou et al., 1 Feb 2026). This suggests that MWP, CHAP, AWCP, and memorywire occupy different parts of an emerging stack: stage-structured orchestration, accountable collaborative workspaces, delegated workspace access, and typed memory operations.

6. Limitations, adoption, and future directions

The MWP paper is explicit that the protocol is not universal. It works best for workflows that are sequential, reviewable, repeatable, artifact-oriented, local-first, and often run by people who want direct control over prompts and outputs. Conventional frameworks are described as preferable for real-time multi-agent collaboration, high concurrency or many simultaneous users, complex automated branching, and robust error handling with retries, fallback logic, and exception management. MWP is sequential by design, with conditional branching usually human-decided between stages and failure often handled by manual rerun or intervention (Clief et al., 17 Mar 2026).

Several failure modes are identified. Stage scoping can be poorly designed, reference material can be underspecified, human edits may patch symptoms rather than root causes, final-stage misalignment can emerge from earlier stage drift, and scaling MWP toward automation risks reintroducing framework complexity. The discussion of stage-3 animation misalignment is presented as a concrete example in which timing, visual density, and phrase alignment drift from the script unless explicitly audited (Clief et al., 17 Mar 2026).

The paper also reports early deployment evidence. It describes an open-source repository and recommends Git because prompt edits are diffable, stage outputs are versioned, and the whole workspace acts like “infrastructure as code” for AI workflows. It also introduces a workspace-builder, itself implemented as an MWP workspace, with five stages: discovery, stage mapping, scaffolding, questionnaire design, and validation. External adoption is mentioned at the University of Edinburgh’s Neuropolitics Lab, ICR Research, and the Academy of International Affairs in Bonn, though details are limited by NDAs. Informally, the paper reports a 52-member practitioner community and a U-shaped intervention pattern across 33 users of multi-stage workspaces: heavy editing at stage 1, lighter editing in middle stages, and heavy editing again at final stage. It further reports that non-technical users successfully edited CONTEXT.md files to change stage behavior, and that some users with no prior coding experience created and ran workspaces using the workspace-builder (Clief et al., 17 Mar 2026).

Future directions push the compiler analogy further. The paper suggests multi-pass incremental compilation, in which each stage produces an intermediate representation and only changed downstream stages need rerun. It proposes semantic debugging mechanisms such as provenance identifiers in outputs, links from output text back to source instructions, and cross-stage verification sections. It also advances an “edit-source” principle: if the same corrections recur, the real fix may belong in the stage contract, the voice guide, the reference materials, or earlier stage framing, rather than in repeated manual patching of outputs. This suggests an interpretation of MWP not merely as a lightweight orchestration pattern, but as a filesystem-native protocol for inspectable, editable, and versionable context engineering (Clief et al., 17 Mar 2026).