Source: Dev.to

The drift problem nobody told you about

If you have used Claude Code, Cursor, Aider, or any other AI‑coding agent across more than two projects, you have felt this:

1. Project A – copy the .agents/ folder (or CLAUDE.md, or .cursorrules) from your last project, tweak two things, done.
2. Project B (six weeks later) – copy from Project A, tweak three things this time. Now A and B are different.
3. Project C – the AWS safety rule looks one way in A, slightly different in B, and you don’t remember which one was correct. The deploy skill exists in three subtly different versions. The MCP setup is in two of the three repos.

This is drift, and it is the silent killer of productivity once you start using AI agents seriously across a team.

The other failure mode is bloat: every .agents/ folder ends up as 200 files no one owns, no one knows what is still relevant, and “let me add one more rule just in case” wins every code review.

---

How the infrastructure world solved this

Before 2014 you would SSH into a server, install packages, edit nginx.conf, and hope you remembered to do the same on the next server. Then Terraform happened: declare the desired state in HCL, run terraform apply, and the world matches your file. State drift becomes detectable, reproducibility becomes free.

Agent Workspace as Code (AWaC) applies the same pattern to the layer above your code: the rules, skills, workflows, and conventions your AI coding agent reads.

# workspace.yml
schema: workspace/1
name: my-feature
stacks:
  - core                # universal foundation
  - aws                 # AWS safety + terraform parity
  - mcp                 # MCP server bootstrap
  - my-product/agent-stack   # product‑specific stack

Typical workflow

# Resolve stack shortcuts via a registry in /agent-stack-core/awac.yml
# Clone each stack repo at the latest commit on main
# Compose .agents/{rules,skills,workflows}/ deterministically — last stack wins on collisions
# Generate CLAUDE.md (canonical context file) and AGENTS.md (mirror for non‑Claude agents)
# Emit a workspace.lock.yml recording exact commits

That is the whole loop. Same workspace, every machine. No copy‑paste. No drift.

---

Stack layout

A stack is a plain GitHub repo with this layout:

my-stack/
├─ awac.yml          # metadata: which product, which repos to clone
├─ rules/            # behavioral rules (always_on or trigger‑based)
├─ skills/           # named procedures the agent invokes by reference
├─ workflows/       # multi‑step processes
└─ templates/       # workspace.yml templates (optional)

The reference public stacks (under getGanemo/agent-stack-*) cover universal needs (core), AWS, MCP, Cloudflare, and research/branding/thesis templates. You can publish your own – anything matching the convention is a valid stack.

---

Agent‑first CLI design

• Every command accepts --json and emits structured output.

• Errors carry four fields:

  {
    "code": "WSP_007",
    "category": "environment",
    "cause": "gh CLI not authenticated",
    "remediation": "Run: gh auth login"
  }

  This lets an agent run wsp doctor, read the structured error, and either fix it automatically or surface the full context to a human. No paragraph‑reading, no guessing.

Error‑handling is ~80 % of the difficulty for long‑running agent loops in production. Stable error codes are the closest thing we have to a contract between CLI and agent.

---

Frequently mentioned “non‑features”

Every contentious choice generated an Architecture Decision Record (ADR). They are in the docs repo and worth a skim even if you don’t adopt the tool – most of them are trade‑off discussions you will face if you build something similar.

Sample ADRs

• 001 – The unit of composition is the workspace, not the project, the org, or the user.
• 004 – CLAUDE.md is canonical, AGENTS.md is a mirror. Reasoning explained.
• 007 – The CLI is agent‑first, not human‑first. Implications for command surface, errors, output.
• 010 – DevVault is a two‑layer model (versioned per‑product catalog + non‑versioned per‑machine vault path).
• 012 – Distribution via GitHub Releases, not PyPI (for now).
• 014 – AWaC stays open‑source. No SaaS planned.

All ADRs are available at .

---

Install

# Get the latest tag
TAG=$(gh release view --repo getGanemo/workspace-cli --json tagName -q .tagName)

# Download the wheel
gh release download "$TAG" \
  --repo getGanemo/workspace-cli \
  --pattern '*.whl' \
  --dir /tmp/wsp

# Install via pipx
pipx install /tmp/wsp/wsp-*.whl

---

Compose a workspace

mkdir my-feature && cd my-feature
wsp init my-feature --template blank
wsp bootstrap

Two minutes from clone to a working workspace.

---

What we need from you

The thing I most want from this launch is honest feedback on the abstraction, not stars (though they’re nice).

• What rule of yours does not fit cleanly into a stack?
• What composition pattern do you have that AWaC cannot express?

Please let us know – your input will shape the next iteration.

Questions

• What error message confused you?
• What stack should exist that I have not built?

If you have 5 minutes after trying it, open an issue or reply on this post. The roadmap is public ([Roadmap issue]) and 👍 reactions move things up.

Thanks for reading. Built solo, MIT, no SaaS, fork‑friendly. See you in the issues.

— Fernando
github.com/GanemoCorp · ganemo.com