Acta Technical Specification

Optimized Multi-Repository Developer & Agent Workspace Orchestrator

1. Executive Summary & Core Paradigm

Traditional multi-repository management relies on Git submodules or Git worktrees. Submodules introduce fragile pointer references, detached heads, and massive overhead when dealing with rapid cross-repo iterations. Worktrees require sharing a single underlying Git directory, which often leads to tracking conflicts, locked branch states, and unexpected path-resolution failures when executing heavy local runtime environments or hooking in AI developers (e.g., Claude Code, Cursor, OpenClaw).

Acta radically simplifies this architecture by treating the multi-repo development loop as an isolated workspace of autonomous physical clones nested cleanly inside a single parent configuration repository.

acta-workspace/ (Controlled config & custom skills repo)
├── .gitignore (ignores clones/)
├── acta.yaml  (Defines target repositories, setups, setup-scripts, & environments)
├── skills/    (Custom developer agent tools, system prompts, CLI harnesses)
└── clones/    (Clean, independent physical clones - totally decoupled from worktree lockouts)
    ├── backend-service/
    ├── frontend-app/
    └── library-dep/

By leveraging dedicated clones dynamically isolated within a gitignored directory, Acta provides the unified, concurrent execution benefits of multi-worktree systems with none of the typical locking, indexing, or dependency isolation headaches.

2. Dynamic Clones Architecture

Instead of mapping multiple working trees back to one hidden .git folder, Acta spins up independent physical clones pointing to a unified configuration.

Isolation from Parent Tracking: The .gitignore at the root of the Acta workspace strictly hardcodes /clones/.
Concurrent Non-Blocking Operations: Developers or AI agents can run completely distinct branch structures, package installations, and builds concurrently without mutating shared .git/index structures or breaking hot-reloads.
Unified Clone lifecycle:
- acta clone: Reads acta.yaml, pulls baseline clones of all specified component repositories in parallel into /clones/.
- acta sync: Pulls, stashes, or rebases all clones matching a specific wildcard branch across the workspace (e.g., matching a feature path like feature/auth-upgrade).
- acta clean: Safely purges working directory artifacts without destroying local stashes.

3. Integrations: Herdr & CMux

To make multi-clone setups usable, Acta serves as a control plane that integrates natively with modern execution/terminal Multiplexers and Orchestrators:

Herdr (herdr.dev) Integration: Acta uses its centralized acta.yaml file to dynamically generate herdr configuration manifests. Since herdr specializes in executing commands across multiple local directories, Acta orchestrates parallelized builds, lint sweeps, or status checks automatically matching the current clones list inside /clones/*.
```
# Acta automatically compiles targets and passes them dynamically to Herdr
acta exec "npm run build" --parallel
```
CMux (Terminal Multiplexer) Orchestration: When orchestrating local microservices alongside frontend development, Acta hooks direct process groupings into cmux. Running acta dev reads the startup requirements from the configuration and automatically maps standard out/in to categorized cmux windows (e.g., Window 0: acta-clipboard-daemon, Window 1: backend-service, Window 2: frontend-app).

4. The Acta Clipboard & Multi-Agent Clipboard Stack

A major friction point when working across distinct codebases is sharing state, compiler errors, build outputs, or exact instructions between repos—especially when relying on external or local LLM prompt contexts.

The Acta Clipboard operates as an intelligent background stack daemon. Rather than overriding your primary operating system clipboard destructively, it introduces a "Clipboard Stack". This allows developer agents (e.g., Claude Code, local helper daemons, or custom MCP wrappers) to push artifacts, context segments, compiler warnings, or command outputs onto a dedicated stack history that the user can cycle, pop, or filter at will.

[Agent / CLI Process 1] ───(Push: Config Error)────┐
                                                   ▼
[Agent / CLI Process 2] ───(Push: Schema Diff)────► [ Acta Clipboard Stack ] ───► Pop / Cycle ───► User Clipboard
                                                   ▲
[Manual Clipboard Copy] ───(Push: Code Snippet)───┘

System Architecture & The "Stack" Paradigm

In a standard workflow, if an agent copies a code block or deep-link trace to the clipboard, it instantly blows away whatever code you were currently holding to paste elsewhere. Acta Clipboard solves this with a structured, agent-friendly stack interface.

The Clipboard History Stack: Acta hosts a local memory buffer of the last $N$ items pushed by agents, compilers, or manual runs.
Deterministic Agent Access: When an agent runs a task in a clone (e.g., generating a migration script or diagnostic output), instead of executing a standard platform copy command, it uses acta clip push.

Clipboard Commands & Features

acta clip push [--tag <metadata>] Pushes a new content block onto the top of the stack.
```
cat clones/backend/schema.ts | acta clip push --tag schema
```
This preserves the previous items already in your clipboard history, avoiding immediate loss of developer context.
acta clip pop Pops the top item off the Acta Stack and forces it onto the actual system physical clipboard for direct Cmd+V / Ctrl+V pasting.
acta clip list Dumps an indexed overview of your active stack history showing tags, origin repository, timestamps, and size, letting you select exactly which index to promote.
```
[0] - tag: schema (backend-service) - 5s ago
[1] - tag: build-error (frontend-app) - 1m ago
[2] - tag: snippet (library-dep) - 5m ago
```
acta clip cycle / acta clip toggle A fast shell shortcut or global keyboard hotkey action that cycles the system OS clipboard rapidly through active items in the Acta stack, making cross-clone manual context transport trivial.

Multi-Agent Context Injection

Because items are kept in a structured stack, a user can write a prompt in their desktop environment or chat shell saying: "Write a helper function for ditto-app matching the schema in the top of the clip stack." The agent-harness context provider intercepts this, reads down into the Acta Stack, extracts index [0], and seamlessly packages it:

<acta-context clone="backend-service" source="clipboard-stack-0" tag="schema">
// Payload dynamically injected for the agent...
</acta-context>

5. Agent Harness, Skills API & Bootstrap Config

Acta doesn't just manage the directory layout; it packages a custom Agent & Skill Harness directly inside the parent repo. If you switch machines, cloning the parent Acta repo restores both your code directories and the automated developer agents tailored to interact with them.

`acta.yaml` Schema

name: core-platform-workspace
version: "1.0.0"

repos:
  gateway:
    url: "[email protected]:omniaura/gateway.git"
    branch: "main"
    setup: "go mod download"
  
  ditto-app:
    url: "[email protected]:omniaura/ditto-app.git"
    branch: "main"
    setup: "npm install && npm run build:prep"

# Registered execution groups
harness:
  default_agent: "claw-coder"
  agents:
    claw-coder:
      engine: "openclaw"
      workspace_override: "/clones/ditto-app"
      api_key_env: "OPENROUTER_API_KEY"
      system_prompt_path: "./skills/coder_system_prompt.md"

skills:
  - name: "db-migrate"
    run: "cd clones/gateway && go run scripts/migrate.go"
    trigger: "post-sync"
  - name: "verify-types"
    run: "cd clones/ditto-app && npm run build"

The Setup Loop

Clone Parent Workspace: Pull the core Acta control repository containing your custom configurations and agent setups.
Setup: Run acta bootstrap. It initializes .gitignore, reads acta.yaml, parallel-clones the repos down into /clones/, runs individual setup scripts sequentially or in parallel, and verifies system dependencies.
Trigger Agents: Run acta run <agent-name> --task "Integrate core storage specs into ditto-app backend hooks". Acta routes this directly to the configured agent, locking the target clone's folder scope to prevent pollution of surrounding sibling repos.

acta_spec.md