A stronger agent harness for ultra-long-horizon coding — with a visible multi-agent TUI workspace.
Lineage: Trellis (workflow engine) × CodeTeam methodology (a distilled HarnessStack discipline layer) × CCB (visible multi-agent runtime).
中文说明见 README.zh.md。
Apache-2.0 · overlay for Trellis · deps: Trellis + CCB — AGPL, installed separately, not bundled · 中文 README
What it is. Arbor is an adoptable overlay that turns Trellis into a harness built to survive ultra-long-horizon coding — one goal spanning dozens of sessions, many concurrent sub-tasks, needing audit and rollback. Who it's for. Teams (or a solo dev) running multi-session AI coding who have hit the wall where a single agent loses the plot across sessions, gates get silently skipped, and there is no clean way to roll a harness change back. What it solves. It layers role tiering, explicit gates, layered memory, semantic cross-session handoff, and a visible multi-agent runtime on top of Trellis — without ever polluting your product repo.
Three pillars:
- Trellis — the workflow engine (3 phases Plan/Execute/Finish, task system, per-turn breadcrumb).
- CodeTeam methodology — the discipline layer: L1–L4 role tiering, explicit gates (incl. auto-judge/HITL), layered memory (RepoMem + ADR + promotion gate + challenge-before-ack), multi-lens verification, sendbox semantic handoff, a pending-actions Dashboard, and a task ledger.
- CCB — a visible, controllable multi-agent runtime (rootorc/suborc/impler as real terminals in tmux panes;
askA2A auto-replies + retries). It takes over the live multi-agent coordination action layer.
Three-layer division: ledger = your issue tracker · durable semantic handoff = sendbox · transient live coordination = CCB (see ccb-integration.md).
Arbor is not a fork of Trellis or CCB. It is an adoptable overlay that never pollutes the product repo (.git/info/exclude + a separate local hgit history repo).
| Capability | Trellis native | Arbor adds |
|---|---|---|
| Role / task tiering L1–L4 | parent/child + subagents | explicit RootOrche / SubOrche / Impler / subagent, each running a tailored slice of the pipeline; lifecycle walkthroughs |
| Gates & audit | task/commit confirm | four-level Execution Policy (auto / auto-judge / ask-first / HITL) + Skip Bias + no-silent-skip audit |
| Layered memory | spec update + journal + mem | three-tier epistemics + ADR (with Origin traceability) + Document-Boundary table + Pairing Rules + HITL promotion gate + challenge-before-ack |
| Verification | single check | multi-lens: check + behavior self-verify + dependency security-scan as a hard MR gate + human smoke |
| Cross-session handoff | mem/journal (recall) | sendbox directed letters (absolute read_first + process-completeness + lifecycle/WIMTB) |
| Cognitive load | breadcrumb/statusline | Dashboard — one projection of "what does the human owe now" across sessions |
| Persistence | local files | task-ledger mirror (one task = one issue, parent/child ↔ L3/L2, WIMTB on finish) |
| Code intelligence | grep/glob | codegraph MCP (symbols/callers/impact) feeding red-team evidence + promotion discipline |
| Multi-agent runtime | one-shot subagent | CCB (visible tmux-pane agents + ask A2A auto-reply/retry); durable → sendbox, tasks → ledger |
| No product-repo pollution | .trellis/ committed |
.git/info/exclude overlay + separate hgit history — versioned/rollbackable, never in feature branches/push |
| Methodology corpus | — | 9 methodology/ clusters distilled from real projects |
Adopt Arbor if you run AI coding across many sessions on one long goal, coordinate more than one agent at a time, and need the work to be auditable and reversible — and you want that discipline without committing harness files into your product repo.
You probably don't need it (yet) if your work is single-session, one-agent, short-horizon tasks — plain Trellis (or no harness at all) is lighter. Arbor's value shows up exactly when a session boundary, a concurrent sub-task, or a "how did we get here?" audit would otherwise cost you.
Everything beyond the base overlay is opt-in: the task ledger, CCB multi-agent runtime, and codegraph are all optional. The minimum that delivers value is adopt.sh + pasting the workflow customization block.
Option A — hand a prompt to an agent (recommended). Paste the bootstrap prompt in INSTALL.md into a fresh coding-agent session opened in your repo; it installs the dependencies (Trellis, and optionally CCB / codegraph), runs trellis init, clones Arbor, and runs adopt.sh.
Option B — manual.
npm i -g @mindfoldhq/trellis # required; optional: @seemseam/ccb, codegraph
trellis init --claude --codex -u <your-name>
git clone https://github.com/JasonJarvan/arbor.git /tmp/arbor
bash /tmp/arbor/adopt.sh # lays overlay, writes .git/info/exclude, builds local history repo
# restart your AI sessionStep-by-step adoption + adaptation checklist: ADOPT.md.
Into an otherwise untouched repo, adopt.sh lays down — all hidden from your product git via .git/info/exclude:
.trellis/spec/guides/— the discipline + methodology guides (index), read on demand by your agent during Plan/Execute/Finish..trellis/workflow.md— after you paste the customization block, the pipeline (gates, verification topology, promotion gate) is live..work_context/— sendbox (directed handoff letters) + Dashboard (pending-actions projection) scaffolds..harness-vcs/+hgit— a separate local history for the harness, sohgit log/hgit checkout <sha>roll changes back independent of your productgit.
Restart your AI session and the guides + workflow customization take effect. git status on your product repo stays clean — none of the above is visible to it.
- Overlay —
overlay/lays into your project's.trellis/spec/guides/,scripts/,.work_context/templates + a workflow.md customization block. - Invisible to the product repo — those paths go into
.git/info/exclude(per-clone, uncommitted) → product repo / feature branches / push never see them. - Rollbackable — a separate git repo (
.harness-vcs, no remote) + anhgitwrapper versions the harness;hgit log/hgit checkout <sha> -- <path>to roll back, decoupled from productgit. - Team / multi-machine —
hgit remote add+ push to share; or Trellis's native--workflow-source.
Three repos, kept deliberately separate:
┌──────────────────────────────────────┐
│ Arbor template repo (this repo) │ Apache-2.0
│ overlay/ guides · scripts · templates│ generic; placeholders <REPO_ROOT>/<project>
└───────────────────┬──────────────────┘
│ adopt.sh (lay overlay + specialize placeholders)
▼
┌──────────────────────────────────────────────────────────┐
│ Your product repo (git) │
│ │
│ src/ ................... your code — committed/pushed │
│ .trellis/spec/guides/ ... overlay (the harness) │
│ .git/info/exclude ........ makes the overlay │
│ INVISIBLE to product git │
└───────────────────────────┬──────────────────────────────┘
│ harness changes versioned by
▼
┌──────────────────────────────────────────────────────────┐
│ .harness-vcs (hgit — local git repo, no remote) │
│ hgit log · hgit checkout <sha> -- <path> (rollback)│
└──────────────────────────────────────────────────────────┘
Your product remote never sees the harness; the harness has its own history you can roll back; Arbor upstream stays generic so improvements flow both ways (see arbor-sync).
The core of Arbor is its discipline + methodology guides, laid into .trellis/spec/guides/. Full index with "when to read" cues: overlay/spec/guides/index.md.
| Guide | What it covers |
|---|---|
| Roles & tiering L1–L4 | RootOrche / SubOrche / Impler / subagent + per-tier pipeline slices + lifecycle scenarios |
| Execution Policy & Skip | four-level gates (auto / auto-judge / ask-first / HITL) + Skip Bias + no-silent-skip audit |
| RepoMem: doc boundary & promotion | three-tier epistemics + Document-Boundary authority table + Pairing Rules + persist discipline |
| Verification & Gates | multi-lens verification + security-scan hard MR gate + review + challenge-before-ack |
| Sendbox handoff | cross-session directed letters (absolute read_first + process-completeness + lifecycle/WIMTB) |
| Dashboard | single projection of "what does the human owe now" across sessions |
| CCB integration | visible multi-agent runtime; transient ask vs durable sendbox; permission safety |
| HS 15-step mapping | HarnessStack 15-step → Trellis phases / guides crosswalk |
| Methodology clusters | 9 clusters (LLM testing / verification / contract drift / MR / dependencies / errors / local docs / handoff attribution …) |
| ADR template | architecture decision record (three-gate self-check + Origin traceability) |
Replace placeholders when adopting: <REPO_ROOT> (your repo's absolute path), task-ledger env (Multica, or your own tracker), subtree/language + security scanners, git/MR conventions, local-docs convention. See ADOPT.md.
overlay/spec/guides/ # discipline + methodology guides (the core)
overlay/scripts/ # trellis_multica_sync.py (env-configured) + hgit
overlay/work_context-templates/ # sendbox (toAgent/toHuman) + Dashboard scaffolds
overlay/ccb-templates/ # .ccb/ccb.config example (L1–L4 → CCB agents)
overlay/workflow-customization.md # the workflow.md customization block
skills/arbor-sync/ # bidirectional overlay sync (de-privatize + conflict mediation)
INSTALL.md · adopt.sh · ADOPT.md # install prompt + one-shot adopt + guide
Arbor is a corpus of generalized engineering discipline — contributions of new methodology clusters, guide improvements, and adopt/sync tooling are welcome. Ground rules: keep guides generic (placeholders, no absolute paths / internal names / secrets), never paste text sourced from the AGPL dependencies, and use English commits. See CONTRIBUTING.md.
Arbor itself (guides / scripts / config templates / docs) is open-source under Apache-2.0 — see LICENSE.
Dependencies are separate and not bundled: Trellis (AGPL-3.0-only), CCB (AGPL-3.0-only), and optional codegraph / Multica are installed by you and remain under their own licenses. Arbor interoperates with them via the CLI as separate processes — it is an interoperability overlay, not a derivative work, and redistributes none of their code.