Skip to content
← All chapters

Chapter 05

Repository archetypes

Before an agent changes a single line, it makes one decision that shapes everything after it: what kind of repository is this? The archetype it infers sets the boundary it will reason within for the rest of the engagement — how it onboards, how far a plan reaches, and where state lives. Get it wrong and the agent scopes work to the wrong surface, the most common source of drift on long-horizon tasks. Get it right and it can run autonomously for hours, because plans, onboarding, and state all line up with the real shape of the code.

DWP recognizes three archetypes. Most repositories are the first; the second exists for the teams who coordinate many; the third covers the long-lived workspaces of autonomous agents.

Individual repository

The common case: a self-contained codebase — an application, a library, or a service. There is one coherent surface to reason about, so plans operate directly on the code in the repository and onboarding reads the repository’s own structure and conventions. The agent holds the whole codebase as its context and works it end to end.

Characteristics:

  • A single coherent codebase.
  • Plans modify files in this repository.
  • The .dwp/ workspace lives at the repository root.

Orchestrator hub

The coordination case: a repository whose job is to manage other repositories. Here the unit of work is not a file but a child repository, so plans may spawn child plans in sub-repositories, and onboarding reads the hub’s registry of managed repositories rather than a single codebase. The agent reasons about boundaries and handoffs — which repository owns which work, and how their state stays consistent.

Characteristics:

  • Coordinates multiple sub-repositories.
  • Plans may delegate to child plans.
  • Maintains a registry of managed repositories.
  • The .dwp/ workspace at the hub root tracks cross-repository state.

Agent workspace

A third archetype, added in v2.2, describes something that is a workspace before it is a repository: the long-lived home of an autonomous agent. An OpenClaw workspace, a Hermes service directory, a personal-assistant daemon’s data directory, a cloud agent’s persistent volume — each has plans to execute, tools to use, and memory to maintain, but may not have a codebase to ship.

The key insight is that the harness is a workspace, not specifically a repository. Every element DWP installs into a repository — AGENTS.md, docs/, .agents/, .dwp/ — has a direct workspace equivalent. The methodology’s surface maps cleanly: standing-context files replace the root AGENTS.md, a platform skill directory replaces .agents/, and the .dwp/ folder at the workspace root is unchanged. What changes is the role of git. In a repository, the git log carries state and makes plans resumable across sessions. In a workspace without git, state.json does that job — which is why the machine-readable state layer is required for agent workspaces.

The practical payoff is overnight unattended plans. On OpenClaw-class platforms, a heartbeat or cron turn wakes the agent, runs the DWP resume protocol, executes the next atomic task, updates state.json, and yields. The plan — not the session — is the unit of continuity. A multi-day plan survives restarts, model swaps, and session boundaries because everything the next turn needs is in the plan files: the goal, the checked-off progress, the gate records, and the exact checkpoint inside the current task.

Characteristics:

  • The working directory of an autonomous agent platform.
  • AGENTS.md, .agents/, and .dwp/ at the workspace root.
  • Git is recommended, not required.
  • state.json is required when git is absent, and for any unattended run.
  • Plans typically run unattended, driven by a scheduled heartbeat or cron.

Classification heuristic

The three archetypes look different on disk, and the agent decides among them from signals it can verify — not a label it is told. The decision tree below shows the path; in short, classify as an agent workspace when platform-identity signals are present, as an orchestrator hub only when the evidence demands it, and as an individual repository otherwise.

An agent should first look for agent-workspace signals: a platform identity file (such as OpenClaw’s SOUL.md or HEARTBEAT.md), no primary application stack, and content that is predominantly the agent’s own state. If those are absent, it looks for orchestrator signals: multiple nested git repositories or submodules, a registry or manifest of managed repositories, or configuration that points to external repositories. In the absence of both, it treats the target as an individual repository — the safe default, because over-scoping a plan across boundaries that do not exist is worse than working within one that does.

How onboarding differs

The archetype is not a cosmetic label; it changes what the agent reads, what a plan may touch, and where state is recorded.

Aspect Individual Orchestrator Agent workspace
Scope This repository Multiple repositories The workspace and its plans
Onboarding Repository structure Hub registry Platform files + workspace conventions
Plan target Local files Child plans Local or external repositories
State Local .dwp/ Cross-repository .dwp/ .dwp/ + state.json (required without git)

The practical effect is that an individual-repository agent reasons about one codebase end to end, an orchestrator agent reasons about coordination across repositories, and an agent-workspace agent reasons about continuity across sessions — what was planned, what ran, what is blocked, and what comes next.

This is what lets an agent work autonomously for hours without supervision: by fixing the archetype first, it scopes plans, onboarding, and state to the right boundary, so every task from the first to the last operates on the correct surface.