amber-protocol

Amber Protocol

Governed Agent Harness for real engineering systems.

**Amber Protocol is the governed execution boundary between AI agents and real

systems.** It governs what an agent may see, use, execute, and emit, with whose

approval, and what evidence proves it — in files beside the code, not in chat history.

Amber Protocol 是 AI Agent 与真实系统之间的治理执行边界。

What is Amber · Who it is for · Journey · Install · Quick Start · Team Replication Charter · 简体中文

For repositories already using coding agents in real delivery work. Plans, evidence, decisions, and handoffs stay inspectable beside the code.

Version: 2.0.2 · Status: Stable · Milestones & test status →

What is Amber?

Amber Protocol is a repository-local governance layer for projects that already use coding agents in recurring, real delivery work. The hard part is no longer only producing code. It is preserving enough trustworthy state for the next person or agent to understand what happened, what was approved, what evidence exists, and what should happen next.

Amber makes that state explicit through plans, sessions, evidence, decisions, and handoffs stored beside the code. Its core outcome is Trusted Continuation: another person or agent can enter without the old chat, identify the current state, and take one correct next step.

Amber = the in-repo team replication layer: how a team safely uses AI on _this_ codebase, written as handoff-ready file evidence.

It sits under your existing coding engine and adds governance plus evidence. It is not another agent runtime, and not an org-scale platform.

Amber is · Amber is not In-repo governance and evidence protocol · Org-scale Skill marketplace / plugin store Reviewable plans / gates / approvals / handoffs · Cross-repo gateway or cross-machine control dashboard Local conventions a team can replicate · A scheduler / daemon that runs your project commands

Layering

Layer · Role Engine · Edit code, call tools, run models and the agent loop (provided by your chosen coding host) Governance (Amber) · Plans, gates, approvals, doctor/audit, handoff; evidence written as repo files Upper Shell (optional) · Consumes Amber via MCP only; must not rewrite the .amber contract or push the agent loop into Amber core

Engines do the work; Amber proves what was done, whether it is safe to keep, and how to hand it off.

What Amber will NOT do

These are product boundaries, not TODOs:

1. Not a replacement for the coding engine / not a general agent runtime
2. No Dynamic Workflow execution, no live subagent dispatch, no automatic execution of your project commands
3. No org-scale marketplace, cross-repo gateway, or cross-machine dashboard. The only scheduler is the experimental amber harness runtime (schedule, tick, daemon), which runs a closed set of Amber-internal proposal jobs and never your project commands
4. No overwrite of existing project docs (init / wiki only create missing files)
5. No filesystem containment: a worktree separates checkout state, but absolute-path writes can still escape it. Containing writes requires OS sandboxing.

The harness, runner, retention, external, breakglass, and sync command families are EXPERIMENTAL. They remain callable and are listed with a marker only under amber --all. Default help keeps audit, init, doctor, next, plan, handoff, and session. Stability is separate from visibility tier.

Full boundaries: Team Replication Charter and SPEC.md.

Who it is for

The target environment is a Coding-Agent-Enabled Repository: maintainers already use one or more coding agents for ongoing delivery under human review. A one-off experiment or a repository that merely installed an agent tool does not qualify.

• Primary user — Repository Maintainer: accountable for the repository outcome and continuity.
• Working user — agent-assisted developer: frames and performs bounded delivery work.
• Decision user — reviewer: makes go/no-go decisions from plans, diffs, and evidence.

Why Amber?

AI coding work becomes easier to trust when the workflow leaves inspectable evidence:

• Continue without the old chat: plans, sessions, evidence, and handoffs make state portable across people and agents.
• Review from repository evidence: decisions rest on inspectable artifacts, not a completion claim in a transcript.
• Recover at the right stage: failures and interruptions remain attached to the step that produced them.
• Keep authority explicit: human approvals and governed boundaries are records, not hidden runtime assumptions.

Product journey

Fit -> Adopt -> First trusted continuation -> Deliver -> Recover -> Review / Accept

Journey · User outcome · Default surface · Completion evidence J0 · Fit · Decide whether Amber addresses a real continuity or review failure · amber audit · Read-only findings and an explicit adopt/defer decision J1 · Adopt · Add the minimum repository-local surface without overwrites · amber init, amber doctor · A repeatable setup check J2 · First continuation · Prove a fresh context can continue one real task correctly · amber next, amber plan, amber session, amber handoff · A new person or agent acts correctly without reading the old chat J3 · Deliver · Frame, authorize, work, prove, review, and hand off/accept · Agent journey; CLI fallback · Plan, session, command evidence, and checkpoint agree J4 · Recover · Resume after failure, pause, or context loss at the correct stage · amber session, amber next, amber handoff · Failure remains visible and the recovery action is bounded J5 · Review / Accept · Make a go/no-go decision from repository evidence · Plans, gates, evidence, Web Viewer · Review and acceptance can be explained without the transcript

Feature, bugfix, and refactor routes remain backend policy. Users keep one frontstage model:

Frame -> Authorize -> Work -> Prove -> Review -> Handoff / Accept

Context repair, continuous improvement, team expansion, and high-assurance operations are conditional paths. They do not block the first Trusted Continuation. See the feature matrix and complete journey definitions.

Installation

From npm (Recommended)

npm install -g amber-protocol
amber --version

From source

git clone https://github.com/Bandersnatch0x/amber-protocol.git
cd amber-protocol
npm install
node scripts/amber.js --version

Upgrading to 2.0.0

2.0.0 is a breaking release: three command families that shipped in 1.6.0 — and were already marked deprecated in its help text — are now removed. Nothing else changed shape: plans, sessions, gates, approvals, evidence, and handoffs keep their contracts.

Removed in 2.0.0 · What to use instead amber agent dispatch\ · review\ · status · amber harness (the Contract → Run → Event spine); amber governance report amber team inspect\ · install\ · pin\ · update\ · rollback · amber maintenance (scaffold drift, artifact drift); amber doctor amber adoption report\ · list\ · index\ · validate\ · compare\ · gate\ · status\ · bundle\ · next-actions · amber governance report; the amber-diagnosis-adoption journey skill

The disposition is recorded, not implied — the removed surfaces and their replacement routes stay readable from the tool itself:

amber harness legacy --target .    # every removed surface with its replacement route

If you pin ^1.6.0, a npm update will not cross into 2.0.0 — that range deliberately stops short of the break. Move to ^2.0.0 once you are off the removed commands.

Quick Start (about 10 minutes)

Use one real task to test whether Amber creates Trusted Continuation. File generation alone is not activation.

# J0 — establish fit without changing the project
amber audit --target my-project

# J1 — install the minimum surface; existing files are skipped
amber init --target my-project
amber doctor --target my-project

# J2 — frame one real goal and follow the state-derived next step
amber next --objective "finish the current API change" --target my-project

# Generate a repository-local continuation bundle
amber handoff --target my-project

Now open a fresh agent session or ask another maintainer to inspect the repository without the old chat. Amber is activated only when that new context can explain the current state and take one correct next step.

init and wiki never overwrite existing files. Default help exposes seven fallback verbs: audit, init, doctor, next, plan, handoff, and session. amber --all keeps the expert and compatibility surface available. See the CLI reference.

Expert path (not the homepage main line): read-only continuous-improvement discovery via amber loop recommend — see the loop sections under "What It Won't Do" below.

Command surface

Default amber --help projects seven primary verbs — the whole journey fits in them. amber --all lists the full surface: expert command families, deprecated profile / task / result, and the six experimental families (harness, runner, retention, external, breakglass, sync), each marked (experimental):

Verb · What it does amber audit · Read-only readiness inspection of a repository amber init · Install the minimum repository-local surface (never overwrites) amber doctor · Validate the Amber setup amber next · Deterministic route advice for a stated objective amber plan · Scaffold a feature plan amber handoff · Produce the portable continuation bundle amber session · Inspect or manage the session lifecycle

Everything else is governance and platform surface, deliberately one flag away in amber --all:

• Context and knowledge — wiki, context request|ingest|verify|refresh|stats, memory, knowledge
• Governed records — artifact, principal, evidence, approval, gate, policy
• Control and assurance — projection, adapter, maintain, retention, external, breakglass, eval run
• Delivery and reporting — sync session, governance report, loop recommend, learnings, break-loop, harness

Hiding a family from the default help changes discovery, never capability: every family is documented in the CLI reference, and amber --help is authoritative for its flags.

Using it in DeepSeek Harness

The overlay ships as a native dsh-plugin bundle:

# Install once; dsh adds the Amber bundle layer to the profile
dsh plugin --profile web add dsh-amber-protocol

# Afterwards a normal start loads Amber (no repeated --patch)
dsh --profile web

On Windows the default port 3080 is often reserved; add --port 13080 if the listener fails.

Unpublished-checkout fallback: if you are developing Amber itself and the bundle is not published yet, use an overlay patch instead. Edit dsh/amber-full.patch.yml, replace /path/to/amber-protocol with this repository's path, and layer it at startup without touching the profile:

dsh --profile web --patch /path/to/amber-protocol/dsh/amber-full.patch.yml

Full notes: dsh/README.md.

Core Concepts

Amber organizes governance into seven control layers, weighted toward safety — the higher the priority, the more of Amber's surface that layer gets:

Layer · Role in Amber · Priority Governance · Approval records, safe defaults, policy boundaries, and adoption controls constrain behavior. · Highest Verification · Doctor, audit, validation, review, and gate surfaces provide explicit checks. · High Observability · Timelines, manifests, ledgers, and reports make behavior inspectable. · High Lifecycle · Routes, sessions, checkpoints, and worktrees organize work locally. · Medium Context · Starter docs, wiki scaffolds, manifests, and handoff artifacts keep project context explicit. · Medium Tooling · CLI commands, schemas, validators, workflow packs, and profiles expose explicit interfaces. · Medium Execution · Gated and capability-bound — governed command execution exists behind four gates plus frozen per-attempt admission; there is no un-gated runtime, and no capability is registered in a vanilla install. · Low

The through-line: strengthen Governance, Verification, and Observability; keep Lifecycle repository-local; avoid drifting into a full agent platform. The governance model maps each layer to concrete commands.

What gets installed — the minimum surface doctor checks for:

• AGENTS.md and CLAUDE.md — agent-facing rules
• feature_list.json — tracked feature state
• PROGRESS.md, session-handoff.md, clean-state-checklist.md, evaluator-rubric.md
• .amber/continuous-improvement/state.json
• a minimal docs/wiki/ — project context, system map, runbook, verification, glossary

All starter files are safe defaults. init and wiki skip existing files and report what _would_ be created in dry-run mode.

What It Won't Do

These boundaries are part of the product, not TODOs:

• No dynamic workflow execution or live subagent dispatch
• No automatic / unattended execution of target-project commands — see "Governed loop execution" below for the one gated exception
• No scheduled / cron / hook-triggered execution of target-project commands; the only scheduler is the experimental bounded H7 maintenance runtime, amber harness runtime
• No external writes (PRs, issue trackers, notifications) except through the experimental external family's registered contracts and approvals; no agent tool-call interception
• No automatic rewrite of existing project docs
• No governed verb-stage execution in a vanilla install: the implementation-owned adapter table ships empty (there is no fallback), so session run stages fail closed until a capability is registered — and registering one is a reviewed code change, not a config edit

Governed loop execution (opt-in, gated)

Since ADR-0003, Amber can run a loop contract's declared governed.command — but only behind four gates: a declarative policy check (.amber/governance/rules.json, deny-wins / default-deny), an explicit amber loop approve (one approval authorizes one run), an isolated git worktree (your main checkout is never the cwd), and a tamper-evident hash-chain ledger. Default loop run is still dry-run; execution needs --execute. The worktree separates checkout state; without OS sandboxing, absolute-path writes can still escape it.

amber loop approve --file <pack> --contract <id> --reviewer <name>
amber loop run --file <pack> --contract <id> --execute
amber loop verify-ledger --contract <id>
amber governance standards --target .   # honest OWASP-ASI coverage of what this does (and doesn't) cover

For the full boundary notes, see SPEC.md.

amber loop recommend — the safe continuous-improvement entry