dadaia-workspace

A local-first, spec-driven workspace that gives AI agents current context, a document-governed lifecycle, visible concurrency and anti-slop boundaries.

A workspace is one folder. You open an agent session at its root. Your projects live in repos inside it, and the governance — AGENTS.md, .agents/, .dadaia/ — sits outside every repo. One workspace holds many projects and a project many repos; it is never a monorepo. Each project is a context: its main repo is the repo where specs/ lives, its associated repos are the others it owns.

What it is and principles

dadaia-workspace is the operating environment around repositories developed with AI agents. Its unit is the context: one main repo, where specs/ lives, plus its associated repos; a single-repo context is the minimal case. Eight pillars:

• Current context — agents bind explicitly and receive only the relevant project, memory, release and task state.
• Documents are the lifecycle — backlog, SPEC, PLAN, TASKS, _RELEASE.json and BUGS.jsonl carry ordered work; no runtime drives agents through steps.
• Deterministic boundaries — path class, bind scope, root hygiene, venv-rooting and the push gate are mechanical, each refusal carrying its own runnable fix; what cannot be mechanical is written as law.
• Visible concurrency — sessions may race, git exposes the overlap, and nothing waits on a lock.
• No mechanism without a demand — a capability exists only while it earns its maintenance cost, and deleted surface beats accreted surface.
• No slop — runtime state, reports, handoffs, caches, projections and temporary files have canonical homes and never leak into repositories.
• Six entry harnesses — Claude Code, Codex, Kimi Code, Cursor, Devin and GitHub Copilot, one registry record each; public assets originate once, stage once, and are read natively or through per-entry symlinks.
• Evidence, never prose — success is evidenced by reviews, task markers, commands and artifacts.

Two usage paths follow — a human drives it from a shell, an agent reads the root AGENTS.md map — and both read one truth: every section below derives from a named memory atom under its content hash.

A human installs and uses it

pip install dadaia-workspace
dadaia init demo --harness claude --repo <clone url>   # workspace + first project
cd demo && eval $(dadaia context bind <ctx> --print-env)
dadaia doctor --context <ctx>     # findings, each with a runnable fix

pip install dadaia-workspace installs the library and one CLI under two names, dadaia and dadaia-workspace, so uvx dadaia-workspace init … runs without an install; the wheel ships the full public asset tree, so init works offline.

dadaia init <dir> --harness <name> [--repo <url>] [--skip-assets] is the only verb that works on an empty directory, and a re-run is idempotent. It provisions .dadaia/.venv, the .dadaia/ zones, .agents/skills and the named harness's projection, seeds the state documents without overwriting them, and (unless --skip-assets) stages and installs the public assets — the one writer of every hook wiring. With --repo <url> it clones the repo into repos/<slug>/, composes the context verbs — create, alive, the bind — and installs the pre-push hook. Without --repo it prints the dadaia context create <name> --main-repo <slug> that makes the first project. dadaia harness add <name> adds a harness later.

dadaia context bind <ctx> writes one session record (context, runtime, pid, bound_at) and acquires nothing; --print-env emits DADAIA_CONTEXT and DADAIA_SESSION_ID for eval $(…). The bind's scope is the context's main repo plus its associated repos, and it drives the injection of the tech stack and the memory catalog digest into the session.

dadaia doctor is the one instance validator. Three sections run in fixed order — workspace, specs, ledgers — each finding one <CODE> <verdict> <message> line, every error-class finding with one fix: <command> line and exit 1; there is no score. --json mirrors the run; --fix is the reaper: it moves slop to .dadaia/reaped/ and deletes only what a TTL expired.

An agent reads AGENTS.md and uses it

The always-on law is the root AGENTS.md map; every governed area carries its own scoped AGENTS.md, and every dd- skill touching an area opens that file first. The map, the scoped files, .agents/skills/dd-* and .agents/agents/dd-*.md are authored once. Codex, Kimi Code, Cursor, Devin and GitHub Copilot read .agents/skills natively; Claude Code reaches skills and personas through per-entry symlinks. A harness differs only in serialization — event names, hook file, answer shape — and adds no behaviour.

The gate is one PreToolUse pre-gate: root whitelist, venv guard, SDD gate, in that order, first block wins; a policy that raises is ALLOW. It blocks exactly three things: a new workspace-root entry, a dadaia/pip/python -m dadaia_workspace run outside .dadaia/.venv/bin/, and a PROTECTED write or a bound session's MUTATING write into a repos/<slug>/ outside its scope. Path classes: ADDITIVE (always writable), MUTATING (everything else, scope-judged), PROTECTED (session records and the projected law). Every BLOCK carries exactly one fix: line, and a contract test feeds each fix back through the gate asserting ALLOW. No lease, lock or wait path exists; the gate reads no _RELEASE.json.

Work runs as candidates inside one live release: a picked set, a grill, SPEC, PLAN and TASKS, one reserved task at a time, [x] only after the reviewer's APPROVED, then closure — memory reconciliation, disposition sweep, the feature -> develop merge. The ledger scripts under .agents/skills/*/scripts/ (bugs.py, backlog.py, release.py, audit.py) are each record's one writer. A bug is proposed to the operator and registered only after confirmation, then fixed on the live feature branch with a RED test. Completed work leaves as a handoff-v1 record, validated by dadaia reports validate.

Documentation

The site is https://marcoaureliomenezes.github.io/dadaia-workspace/:

• Quickstart — install to a bound project, a backlog entry and a live release; positioning — why product repos carry no agent config.
• The bug loop — register, RED, fix, resolve; what the bug ledger taught — measuring the ledger and the fix-chain lesson.
• CLI reference · concepts · getting started · distribution

The standalone skills install without a workspace from the dadaia-skills repository: npx skills add marcoaureliomenezes/dadaia-skills, or as a Claude Code marketplace.

Links

• GitHub — https://github.com/marcoaureliomenezes/dadaia-workspace
• PyPI — https://pypi.org/project/dadaia-workspace/
• Agent index — llms.txt
• Changelog — CHANGELOG.md