ARDS v4.0: The Workspace Release
ARDS extends from a file standard into a workspace standard. Knowledge and context unify: the documents a team shares and the context an agent sees are the same objects, living in a cloud workspace the agent reaches through MCP. The file layer is unchanged — every workspace feature is additive and optional.
From file standard to workspace standard
Through v3, context was something a repository presented to an agent. v4.0 adds a workspace layer above the file layer, born from months of daily production use in a multi-repo, multi-agent company. The workspace is where knowledge lives and where agents are launched; the git repository becomes the tooling shell and archive. The cloud is the source of truth, the file layer is the offline fallback, and export is mandatory — no lock-in, ever.
Workspace Model & Scopes
Five scopes — personal, workspace-private, workspace, repo, public — with hard, credential-enforced isolation between them.
Workspace as Command Center
The workspace is where knowledge lives and agents launch. Cloud source of truth, file-layer offline fallback, mandatory export and anti-lock-in.
Tasks & Stages
An 8-stage lifecycle — todo, research, plan, design, breakdown, build, verify, done, plus blocked — with stage-bound artifacts as agent memory.
Agent Launch & Playbooks
Declared tool allow/deny lists, stage-authority ceilings, heartbeats, and metering for every agent launch.
Skill Runtime & Executable Plans
The dated plan doc is the runtime's input. Journaled, deterministic resume with budget ceilings.
MCP Integration, rewritten
Versioned append-only tool vocabulary, capability tiers (read / write / build), gated availability, workspace-pinned credentials, OAuth 2.1.
Generation & Sync Integrity
Idempotent injection and round-trip verification for generated platform files.
Ratified lifecycle features
Archival lifecycle, root-file inventory, business artifact directories, directory size budgets, and conversation artifacts — drafted in the v3.x cycle, now normative.
Fully backward compatible
A valid v3 project is a valid v4 project. The file layer is unchanged; every workspace feature is additive and optional.
Also new since the last announcement
v3.1 and v3.2 shipped between announcements — here is what they added.
v3.2 — Append-Only Fragment Directories (June 3, 2026)
Concurrency-safe high-churn shared docs. Instead of every session rewriting the same regions of one shared file, each update drops an immutable, uniquely-named fragment into a directory — git auto-merges because no two sessions touch the same file. The committed directory is the source of truth, with a bounded, gitignored rollup view regenerated at the original discovery path.
v3.1 — SurfDoc & Routing (February 23, 2026)
The .surf extension via the format field, topic routing in surfcontext.json, the active-work extraction pattern, the direct bridge strategy, platform command stub delegation, SurfDoc YAML frontmatter, and an extended IP safety schema.
Version history
| Version | Date | Highlights |
|---|---|---|
| v4.0 | 2026-08-18 | The Workspace Release — workspace scopes, command center, tasks & stages, agent playbooks, skill runtime, MCP rewrite, sync integrity |
| v3.2 | 2026-06-03 | Append-Only Fragment Directories for concurrency-safe shared docs |
| v3.1 | 2026-02-23 | .surf extension, topic routing, active-work extraction, direct bridge, command stubs, extended IP safety |
| v3.0 | 2026-02-10 | Guides, checkpoints, evidence epistemology, discovery order, multi-agent coordination, cross-repo refs, IP safety, MCP integration, context budget |
| v2.0 | 2026-01-31 | Skills, research docs, scoring, freshness, token budget |
| v1.0 | 2026-01-15 | Initial release — CONTEXT.md, agents, docs, plans |
Upgrading to v4
All workspace features are opt-in. A valid v3 project is already a valid v4 project — start with a version bump and adopt the workspace layer when you are ready.
- 1
Bump version30 sec
Change version in surfcontext.json from "3.0" (or "3.1" / "3.2") to "4.0"
- 2
Adopt fragment directories5 min
Convert high-churn shared docs (active work, plan index) to append-only fragment directories
- 3
Connect a workspaceOptional
Move shared knowledge into a workspace and connect agents through MCP with workspace-pinned credentials
- 4
Adopt tasks & stagesOptional
Track work through the 8-stage lifecycle with stage-bound artifacts as agent memory
- 5
Define playbooksOptional
Declare tool allow/deny lists and stage-authority ceilings for the agents you launch
- 6
Keep the file layer exportedOngoing
Export workspace knowledge to CONTEXT.md + .context/ so the repo remains a complete offline fallback
Ready to upgrade to v4?
All new features are opt-in. Start with a version bump and adopt capabilities as you need them.
Get Started Full Specification