Metadata-Version: 2.1
Name: dadaia-workspace
Version: 0.4.7
Summary: A local-first, spec-driven workspace that gives AI agents current context, a document-governed lifecycle, visible concurrency and anti-slop boundaries.
Keywords: ai-agents,claude-code,codex,kimi-code,workspace,multi-agent,sdd,spec-driven-development,cli
Author: Marco Menezes
Author-email: marcoaureliomenezes@users.noreply.github.com
Requires-Python: >=3.12,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Provides-Extra: claude-sdk
Requires-Dist: claude-agent-sdk (>=0.2.132,<1.0) ; extra == "claude-sdk"
Requires-Dist: jinja2 (>=3.1,<4.0)
Requires-Dist: jsonschema (>=4,<5)
Requires-Dist: pyyaml (>=6.0,<7.0)
Requires-Dist: rich (>=13,<16)
Requires-Dist: typer (>=0.27.1)
Project-URL: Changelog, https://github.com/marcoaureliomenezes/dadaia-workspace/blob/main/CHANGELOG.md
Project-URL: Documentation, https://marcoaureliomenezes.github.io/dadaia-workspace/
Project-URL: Homepage, https://pypi.org/project/dadaia-workspace/
Project-URL: Issues, https://github.com/marcoaureliomenezes/dadaia-workspace/issues
Project-URL: Repository, https://github.com/marcoaureliomenezes/dadaia-workspace
Description-Content-Type: text/markdown

# dadaia-workspace

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/dadaia-workspace)](https://pypi.org/project/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

<!-- derived-from: product-vision sha256:164c4a8b0eca -->

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

<!-- derived-from: pypi-distribution sha256:c627d9e5be4d -->
<!-- derived-from: workspace-init sha256:ca5c835e94af -->
<!-- derived-from: context-management sha256:0227a5e43894 -->
<!-- derived-from: workspace-doctor sha256:ef9c81d0d181 -->

```bash
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

<!-- derived-from: agentic-entities sha256:98cb81d2e72c -->
<!-- derived-from: sdd-gate-v3 sha256:ea8939698674 -->
<!-- derived-from: release-lifecycle sha256:09607348cc88 -->
<!-- derived-from: bug-ledger sha256:9534ded07707 -->
<!-- derived-from: harness-claude-code sha256:ee2f8a3870b4 -->
<!-- derived-from: harness-codex sha256:868c0a658eab -->
<!-- derived-from: harness-kimi-code sha256:fcfeb26d658b -->
<!-- derived-from: harness-cursor sha256:480b18aa9b61 -->
<!-- derived-from: harness-devin sha256:ab4a32c4a53d -->
<!-- derived-from: harness-copilot sha256:b93cef868a6f -->
<!-- derived-from: agent-comms sha256:c485c616b2df -->

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

<!-- derived-from: pypi-distribution sha256:c627d9e5be4d -->
<!-- derived-from: public-asset-distribution sha256:eb08a2e29f43 -->

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

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

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

<!-- derived-from: pypi-distribution sha256:c627d9e5be4d -->

- GitHub — <https://github.com/marcoaureliomenezes/dadaia-workspace>
- PyPI — <https://pypi.org/project/dadaia-workspace/>
- Agent index — [`llms.txt`](llms.txt)
- Changelog — [`CHANGELOG.md`](CHANGELOG.md)

