Ari’s Space*   est. 2026
Skip to content
ari*s space[ a. ]
← Libraryworkspaces / 2026-04-29

Build Your Workspace Once. Then Don't Touch the Foundation Again.

How three roots make orchestration portable across agents.

8 parts / Hover to explore. Click to read.

How three roots make orchestration portable across agents.

Workspace: briefs + decisions
          | manifest
          +-> vault: source
          +-> output: artefacts
          |
     generated links
          |
    resolve + verify paths
Give orchestration, source and generated output separate homes, connected by a manifest. A folder named output is not automatically disposable; retain anything you cannot regenerate.
Per-workspace manifest templateSymlink generator
WORKSPACE_ROOT, VAULT_ROOT, and OUTPUT_ROOT side by side
Three roots, three jobs

The move that made the problem obvious

I spent a day rebuilding the foundation underneath my projects. The orchestration root held the working instructions for products, brands and active client jobs. Moving it took roughly two million tokens of Opus output, 67 logged steps and a purpose-built migration toolset.

The old structure had accumulated over three years. We had the same folder name nested three levels deep. At that point the path was trying to tell me something.

The useful result of the migration was a separation I wish I'd made earlier: one root for the instructions, one for the source, and one for the output.

What had become tangled

Code, content, configuration, renders, screenshots and plans lived together. Backing up the working instructions meant taking the renders too. Reading a brief could require mounting the encrypted code drive.

Tools, hooks, plugins and native apps also expected specific absolute paths. Moving the root exposed how many places knew its old address.

The instructions were tied to Claude Code's surface. Running the same project through another agent would have required a separate plumbing job. And the .claude/ directory mixed canonical settings with about ten gigabytes of accumulated runtime state.

Each decision had made sense locally. Together they made a move much harder than it needed to be.

Give each root one job

The workspace root holds orchestration. Briefs, manifests, plans, decisions, content drafts and memory. Plain Markdown and YAML that can be versioned and read without opening the source vault.

The vault root holds source and proprietary assets. In this setup it was an encrypted disk image, mounted when needed and otherwise unmounted. Each project had its own Git repository inside it.

The output root holds generated artefacts. Renders, builds, exports and archived datasets went on an external SSD. Reproducible output could be treated differently from the source needed to make it. Keep a backup of anything you cannot actually regenerate; calling a folder “output” doesn't make its contents replaceable.

A per-workspace manifest.yaml records the relationship. A generated links/ folder gives tools convenient paths into it. The goal is to resolve a root in one place instead of writing its current address into every script.

What became easier

The manifest gave a cold session somewhere useful to start: here's the project, here's the source, here's the output, here's its current state.

The small workspace root could be snapshotted independently. The vault could have its own encrypted backup cycle. Large reproducible output no longer had to travel with every copy of a brief.

The working agreement also became portable. Claude Code, Codex or another agent able to read the files could inspect the same briefs, decisions and manifests. Provider-specific hooks still needed their own support, but the project no longer depended on those hooks to explain itself.

The .claude/ layer became an optional addition around a readable workspace.

The agent is a worker. The workspace is the contract.

What the agent did, and what I decided

I chose the architecture. One continuous Opus session handled the migration work: building tools, copying with integrity verification at every step, rewriting paths across thousands of files, making manifests and regenerating links. It surfaced each decision with evidence before acting.

The log contained 67 steps. The source workspace remained untouched; the new workspace was built separately, with zero destructive operations on the source.

That distinction matters. A migration report saying “done” is less useful than an account of what was copied, how it was checked and what still exists in the original location.

Copy the structure, then adapt the paths

Declare the roots

WORKSPACE_ROOT   orchestration (markdown, manifests, briefs, memory)
VAULT_ROOT       source code and proprietary assets (encrypted)
OUTPUT_ROOT      renders, builds, exports (external, disposable)

Export these variables in the shell environment the tools will use. Choose the actual locations for your own machine. The names describe responsibilities, not a requirement to copy my drives.

Put a manifest in each workspace

schema_version: 1
workspace: <name>
type: code | content | utility | hybrid
brand: <brand>
code_root: ${VAULT_ROOT}/<brand>
projects:
  - name: <project>
    code_path: <relative to code_root>
    repo_url: <github>
    output_paths:
      builds: ${VAULT_ROOT}/<...>
      renders: ${OUTPUT_ROOT}/<...>

This is a template. Fill in the actual repository location and project paths before using it. The manifest gives your tools a place to look up those values.

The linked script reads the manifest and writes entries such as links/code, links/renders and links/repo.url. Filesystem objects use symlinks; remote resources use URL files.

Regenerate the links after a move, then check that they resolve to the intended locations. Updating an environment variable only helps if the tools consistently read it.

Resolve paths in the code

Use os.environ['WORKSPACE_ROOT'] or the equivalent in your language. If a tool requires a literal fallback to remain importable, check the environment variable first.

The important part is having one source for the root. A thousand identical hardcoded paths are still a thousand places to get out of sync.

Separate settings from runtime state

Canonical settings, commands and custom skills belong with the material you deliberately maintain and migrate.

Sessions, logs, task records, worktrees and other runtime material need their own policy. Some can be recreated; some contain unfinished work. Identify which is which before a move instead of assuming the whole directory is either essential or disposable.

Keep memory easy to inspect

My arrangement used a small MEMORY.md index pointing to individual <topic>.md files in the agent's project memory directory. Each workspace had a stable slug. Index entries stayed under 150 characters and were grouped as user, feedback, project or reference.

The point is a short index that leads to the relevant note. It shouldn't become another giant document the agent has to read in full.

Isolate the agent-specific layer

For this setup, .claude/ was the Claude Code entry point. Outside it, the workspace used ordinary files and environment-resolved paths.

That makes the next agent's first question much easier: what is this project, and where is the work? It can find the answer without first learning one provider's private conventions.

Try a cold start

Open the workspace as if you were arriving for the first time. Can you find the brief, locate the source, identify the output and tell what should happen next?

Then imagine moving one root or changing agents. Look for the places where an old path or a hidden setting would stop that working.

Fixing those dependencies while the workspace is small is much cheaper than discovering them across three years of projects.

↓Per-workspace manifest template↓Symlink generator script

[ comments ]

guests welcome. members show first in the list

no comments yet. start the thread_

1 / 10