Agent workspace on a workstation

One machine-local folder holds agent-operated utilities and disposable scratch files. Harness spill (oversized tool output the IDE writes) stays in native paths such as .cursor/projects/<slug>/agent-tools — not in this tree.

Architecture context

Harness-neutral architecture ($CODE_ROOT/harness.md, $CODE_ROOT/machine.md).

Sibling patterns

Bitwarden CLI (agents) (utilities example).

Vocabulary

Term Meaning

Agent workspace

Root tree on disk for agent utilities + temp (not the code hive, not spill)

Scratch / temp

Files the agent authors (redirects, probes, migration plans) under temp/scratch/YYYY-MM-DD/

Utilities

Scripts and helpers the agent runs (utilities/<topic>/, e.g. Bitwarden entry)

Spill

Harness-written overflow files — do not move into the workspace

Discoverability link

Short path under home pointing at the canonical workspace root (junction or symlink)

Layout

AGENT_WORKSPACE_ROOT/          # canonical (see harness)
  README.md
  utilities/<topic>/           # AGENT_UTILITIES_ROOT
  temp/                        # AGENT_TEMP_ROOT
    README.md
    harness-registry.json5     # optional: one spill *root pattern* per harness
    scratch/YYYY-MM-DD/

Optional registry file indexes where each harness spills (patterns only — not a per-repo file catalog). Concrete spill paths usually appear in tool output when overflow happens.

Canonical root vs home link

Keep the canonical tree where the OS expects app state; add a link so humans can open ~/AgentWorkspace or %USERPROFILE%\AgentWorkspace without duplicating data.

OS Canonical default Discoverability link

Windows

%LOCALAPPDATA%\AgentWorkspace

Directory junction → %USERPROFILE%\AgentWorkspace

Linux / macOS

$XDG_STATE_HOME/AgentWorkspace or ~/.local/state/AgentWorkspace

Symlink $HOME/AgentWorkspace → canonical root

Record in $CODE_ROOT/harness.md:

AGENT_WORKSPACE_ROOT = …
AGENT_WORKSPACE_LINK = …
AGENT_TEMP_ROOT = …/temp
AGENT_UTILITIES_ROOT = …/utilities

Copy keys from harness.example.md.

Agent behaviors (skills)

Skill When

agent-temp

Writing scratch files, curl -o, redirects — use temp/scratch/ only

agent-workspace-global

User asks for a machine-global or profile-root agent script — route to utilities/<topic>/ unless they explicitly opt out

agent-workspace-migrate

Legacy profile litter, flat AgentTemp, or pre-link cleanup — plan, lock probes, confirm no parallel agents before moves

Portable sources (PR upstream here, not duplicated prose in product repos):

Inventory and install: Skills catalog · Usage.

Anti-patterns

  • Scattering new .ps1 / shell helpers at profile root “for the agent”

  • Mirroring or relocating spill under the workspace

  • Shared cleanup scripts in the agent-rules repo — per-machine plans live under temp/scratch/…/agent-workspace-migrate/ only