~/your-repo $ ace/v1 · ready when your agent is
Stop holding your agent crew together by hand.
You already run coding agents. ACE builds the workspace they live in. One command, run by your agent, writes the arrangement: a terminal tab per project plus a control plane, one browser space per project, a governor over a global worker budget, one supervisor and its workers per project, durable memory per tree, and a task contract that treats DONE as a claim requiring evidence.
npx skills add EnzoVezzaro/ace-proagents
then tell your agent: "build an ACE workspace here". It reads the skill and runs the rest
$ receipts
This page quotes no customers, because none are claimed. The proof here is the kind you can check: every number is a command you can run, and the code that lands in your repo carries its own test.
CI runs the strongest one: it installs ACE into a scratch repository, and the code it wrote there must pass its own 62-assertion proof before the push ships.
$ the problem you already have
Three agents, maybe five, across two or three work areas. The thing holding them together is you: a terminal tab per project that you rename when one dies, a browser profile you hope is the right one, a note about which agent owns which tree, a worker budget nobody enforces.
A supervisor stalls on Tuesday; you notice on Thursday. A worker reports done; the integrated build is red. A model falls back to a paid tier without asking; the invoice explains it a week later. A new session spends its first twenty minutes re-learning what the last one already knew.
This is an arrangement problem, and you can fix an arrangement: write it down, enforce it in code, and verify it before anything reports done.
$ the fix: seven parts, one name
project.id === its tab label === its browser space === basename(its tree)
A project is one name in the terminal, in the browser, on disk and in the governor's report. One place to look for what it touched. The seven parts that make that real, each framed as what it buys you:
agent-skillthe workspace teaches its own operator. The manual installs beside the crew, into .agents/skills/, .claude/skills/ and .opencode/skills/. The next agent reads it before touching anything.herdr-spacesan office with a floor plan. One tab per project plus a control plane, always 1 + N, derived from data. Adding a project adds one tab. Nobody re-edits a config by hand at midnight.ego-lite-spacesbrowser work stays in its lane. One space per project, named after the project. The rule says a second space is never opened to escape a stuck page.governthe governor notices a stalled supervisor in minutes. It checks liveness and evidence-backed progress, swaps dead model routes, and escalates what it cannot fix.supervisors-workersevery task names its outcome before a supervisor dispatches it. One owner per task, lease-backed. A crew that cannot say what done means does not start.accdurable memory per tree: gotchas, decisions, lessons, seeded once and never overwritten. The next session reads for thirty seconds instead of re-learning for twenty minutes.charterDONE means evidence. The handoff convention every mission ends with: files changed, commands run, results, failures, what was not tested. A claim with nothing behind it is recorded unverified.agent-skill → herdr-spaces: the driver herdr-spaces → ego-lite-spaces: project.id ego-lite-spaces → herdr-spaces: browser_space govern → supervisors-workers: cap supervisors-workers → charter: tasks[].outcome acc → govern: memory charter → supervisors-workers: acceptance
Scripts you write by hand arrange; they do not refuse. Here the installer refuses a setup whose names would disagree, the roster refuses an agent named for a project it does not own, and the verifier fails a handoff that lies. The refusals are code with tests, not conventions with intentions.
$ the proof: one real run, verbatim
a repo with two work areas, nothing installed yet. node v26.8.2. trimmed only where marked ⋯. every line kept is unedited output
npx ace-proagents@latest inspect
ACE inspect — demo-repo git no node v26.8.2 manifest demo-repo — scripts: test, build browser not suggested verify npm run test && npm run build projects experiments/alpha-api, experiments/beta-web Answer the intake from these facts: ace setup --goal … --outcome … --projects … (or --intake file.json)
npx ace-proagents@latest setup --goal "ship the reporting API" --outcome "the report page renders under 200ms" --projects experiments/alpha-api,experiments/beta-web
ACE setup — demo-repo intake goal ship the reporting API outcome the report page renders under 200ms projects alpha-api (experiments/alpha-api), beta-web (experiments/beta-web) harness opencode budget 4 worker(s), global across every project browser no proof npm run test && npm run build detected node v26.8.2 plan — 7 part(s), 24 write(s) agent-skill Agent skill — the manual the workspace's own agent loads → .agents/skills/ace/SKILL.md → .claude/skills/ace/SKILL.md → .opencode/skills/ace/SKILL.md herdr-spaces Herdr spaces — one tab per project, one control plane → orchestration/tabs.mjs → orchestration/projects.json ⋯ 6 more under orchestration/ ego-lite-spaces · govern · supervisors-workers · acc · charter ⋯ 13 more writes: the browser space, the governor, the handoff convention, the ace key, memory per tree, the charter layer, STACK.md apply — 24 written, 0 left alone + .agents/skills/ace/SKILL.md + .claude/skills/ace/SKILL.md + .opencode/skills/ace/SKILL.md ⋯ 21 more: the orchestration stack, the ace key (merged, nothing else touched), the ACC control file, one .acc-memory.md per tree, the charter files, STACK.md verify — 18 passed, 0 failed, 2 not run ok herdr-spaces every declared agent resolves to a tab that allows its role control-plane + alpha-api + beta-web ok herdr-spaces tab count is 1 + projects (3) control-plane + alpha-api + beta-web skip herdr-spaces live tab creation (tabs.mjs up) needs a running Herdr session; run `node orchestration/tabs.mjs up --dry-run` inside one ok ego-lite-spaces space for alpha-api equals its id and its tree name alpha-api (alpha-api) ok ego-lite-spaces space for beta-web equals its id and its tree name beta-web (beta-web) ok govern the ace configuration validates spec ace/v1 ok govern the active-agent budget equals the stack's worker cap (4) ace budget 4, orchestration cap 4 skip govern one governor cycle needs live state; run `ace govern` after the first dispatch ok supervisors-workers exactly one supervisor per project 2 project(s) ok supervisors-workers every project has at least one worker 1 + 1 ok supervisors-workers every task names the outcome it produces no task declared yet — an empty queue is allowed, a task without an outcome is not ok acc the ACC control file exists and declares a schema version .acc/config/config.yaml ok acc every project tree has its own memory file 2 tree(s) ok charter the task contract is written charter/TASK-CONTRACT.md ok charter the handoff convention names its fields and its marker found 6/6 markers ok charter the tool registry parses and every entry is named and accounted for 5 entr(ies) ok agent-skill the skill is written and declares its name in frontmatter .agents/skills/ace/SKILL.md ok agent-skill the skill documents the command that builds the workspace names `ace setup` ok agent-skill the skill teaches inspect-before-answering ace inspect --json ok agent-skill every harness copy is byte-identical to the shipped source .claude/skills + .opencode/skills match .agents/skills
The two skips are checks that could not run. Each reports its reason; none of them pass. The install also did not start an agent, create a tab, open a browser space, invent a model route, or write outside your repository. It wrote an arrangement. Starting it is a separate, deliberate step.
the tab contract — one control plane plus one tab per project
ok every declared agent resolves to a tab that allows its role
ok a project with two supervisors is refused
...
selftest: 62 ok, 0 failures (703ms)
note: healthCheck() was not exercised — it needs a real model probe, and this run is offline
node orchestration/selftest.mjs: the code the install wrote, proving itself, offline
$ drive it
After the install, the crew is data and commands: the same words your agent already knows how to run. Nothing here needs a dashboard.
ace inspect --jsonthe repo's facts (work areas, verification scripts, git state) before anything is answeredace setup --dry-runthe whole plan, writing nothing. You read it before your repo changesace setup --jsoninstall and verify. One JSON document out; structured refusals that name the fixtabs.mjs planthe roster and the budget with its source: who runs, where, and why that numbertabs.mjs upinside the multiplexer: create the tabs, start the agents that fit the captabs.mjs governthe governor's brief across every project: liveness, evidence, what's nexttabs.mjs verify · cyclehandoffs checked against evidence; recovery recheck; the next task, or an honest "none"ace task add "…" --outcome "…"a task with no outcome line is refused at the doorace handoff verify a DONE claim with no command that exited 0 does not passace watchdog cyclean independent control plane recovers a dead governor. the governor is not a single point of failure{
"version": 3,
"generated_by": "ace setup",
"cap": {
"max_active_workers": 4,
"scope": "EVERY project tab combined … the control plane is never counted."
},
"harness": {
"default_harness": "opencode",
"model_policy": {
"free_only": true,
"on_no_verified_free_model": "refuse to dispatch and report the
blocker. Never fall back to a paid model silently."
}
},
"projects": [
{
"id": "alpha-api",
"root": "experiments/alpha-api",
"browser_space": "alpha-api",
"owned_paths": ["experiments/alpha-api", "orchestration/state/alpha-api"],
"forbidden_paths": ["experiments/beta-web", "orchestration/state/beta-web"],
"outcome": "the report page renders under 200ms",
"agents": [
{ "role": "supervisor", "name": "alpha-api-supervisor" },
{ "role": "worker", "name": "alpha-api-worker" }
],
"tasks": []
}
]
}
Adding a project, a worker or a task means editing this file. The orchestrator has no branches to edit. The boundaries sit right here: owned_paths is where a project's agent may write, forbidden_paths is everything else. When a spawn exceeds the cap, the orchestrator refuses it and logs the reason. The cap you set holds.
$ the objections, answered
will this burn tokens?no. The install starts nothing, sends nothing, opens nothing. When the crew runs, work goes only to models whose freeness is verified this run: a name containing -free is not evidence. With nothing verified, the orchestrator refuses the dispatch.does it work with my harness?the skill installs into .agents/skills/ (the cross-harness location), .claude/skills/ and .opencode/skills/: one source, three copies, verified identical. Codex, Copilot, Cursor and Gemini CLI read AGENTS.md; point them at the same file. The agents themselves run on opencode, claude, codex, gemini or freebuff panes.do I need the Herdr multiplexer?to install, plan, verify and read state: no, all offline. To create tabs and start agents: yes, tabs.mjs up runs inside a Herdr session, and the install says so instead of pretending.what happens to my files?writes stay inside your repository: the orchestration stack, generated data, memory files, charter, one merged ace key. A file that already exists and differs is left alone unless you pass --force. Memory is seeded once and never overwritten, not even with --force. The installer never publishes, pushes or deploys.am I locked into a model or vendor?the installer writes no route unless you pin one. The model, the multiplexer, the memory layer: every third-party capability is an adapter with a contract, and deterministic fakes ship in the box, so the tests need no credentials.what if it breaks mid-run?recovery is bounded and audited: checkpoint first, hold the lease, respect the restart budget, journal every action to .ace/actions.jsonl. A heartbeat alone never proves progress, and nothing reports a restart it did not deliver. When the chain is exhausted, it escalates to you instead of pretending.why not write my own scripts?you would re-derive seven linked parts, each with its own verifier, and your scripts will not refuse a lying handoff. Each check exists because a crew without it failed. The refusals are the feature.What is absent: no HTTP API yet (the CLI's --json surface is the machine interface), no live provider quota check, no hosted service. See docs/APP-INTEGRATION.md for what a UI could consume today.
$ get it
Install the skill the way your harness prefers, then tell your agent what to build. Every route installs the same manual. The loop it teaches is six commands, and git reverses every write.
any harness · one command
npx skills add EnzoVezzaro/ace-proagents
the cross-harness installer: claude code, cursor, codex, copilot, windsurf, gemini, cline, opencode and more.
claude code · native plugin
claude plugin marketplace add EnzoVezzaro/ace-proagents && claude plugin install ace@ace-proagents
this repository is its own plugin marketplace: the skill rides in the plugin.
no install at all
npx ace-proagents@latest setup --goal "…" --outcome "…" --projects a,b --json
the CLI is the whole product, from npm 0.2.0. The skill is its manual; your agent reads it in the repo it builds.
the loop the skill teaches: every step a command your agent runs and reads
load the skillSKILL.md: installed into the workspace it buildsace inspect --jsonthe repo's facts, before anything is answeredanswer from evidencethe intake: never invented, or the install refusesace setup --dry-runread the plan; your repo is untouched until you say goace setup24 writes, 18 checks, 2 honest skips: the arrangement landsdrive the crewtabs.mjs plan · up · govern · verify: evidence or silence
npx skills add EnzoVezzaro/ace-proagents && cd /path/to/your-repo && ace inspect --json
MIT · zero dependencies · nothing written outside your repo · undo with git
ace/v1 · what ACE is today