Amber Protocol

简体中文

Status: Stable | Version: 1.3.11 · Milestones & test status →

Make AI coding sessions reviewable, gated, and handoff-ready.

Getting started · CLI reference · Governance model · Examples · Roadmap

What is Amber?

Amber Protocol is a repository-local governance layer for AI-assisted engineering. When a team lets an AI agent work inside a repo, the hard parts are no longer just writing the code. The hard parts are knowing what was done, whether it is safe to keep, how to hand it off, and how to prove it was reviewed.

Amber makes those parts explicit: it prepares agent-facing context, records approvals and gates, verifies state with read-only checks, and produces handoff and audit artifacts as files inside your repository.

It is deliberately conservative. Amber creates review artifacts, dry-run plans, and approval records. It does not run dynamic workflows, invoke live subagents, execute your project's commands, or rewrite your existing docs.

Why Amber?

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

• Reviewable by default: plans, gates, ledgers, and handoffs live in the repo instead of in a chat transcript.
• Dry-run first: setup, audit, route, and loop commands expose intent before changing state.
• Human gates stay explicit: approvals are records a reviewer can inspect, not hidden runtime assumptions.
• Agent context is local: AGENTS.md, wiki files, feature plans, and session handoffs travel with the codebase.

Lifecycle map

audit -> init -> governance report -> next -> plan -> gate -> verify -> approve -> handoff bundle -> handoff validate

Stage	Command	What you get
Inspect	amber audit --target <repo> --summary	Read-only readiness findings
Install	amber init --target <repo>	Starter governance files without overwrites
Score	amber governance report --target <repo>	Readiness score, risks, and structured next actions
Effectiveness	amber workflow assess --target <repo>	Workflow-effectiveness dimensions (separate from readiness; ADR-0008)
Plan	amber plan --target <repo> --feature F001 --title "..."	A feature plan and review surface
Gate	amber next --target <repo>	The next safe lifecycle command
Verify	amber doctor --target <repo>	Checks for required agent-facing surfaces
Handoff	amber handoff bundle --target <repo>	Portable continuation bundle another human or agent can continue

Repository artifacts

Amber is meant to be inspected as files:

AGENTS.md
CLAUDE.md
feature_list.json
PROGRESS.md
session-handoff.md
clean-state-checklist.md
docs/wiki/
.workflow/continuous-improvement/state.json

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

From GitHub Packages

Amber Protocol is also published as a scoped package on GitHub Packages (@bandersnatch0x/amber-protocol). Consuming it requires a one-time .npmrc setup:

# 1. Create a GitHub PAT with read:packages scope at https://github.com/settings/tokens

# 2. Copy the template and replace the token
cp .github/npmrc-github-packages .npmrc
# Edit .npmrc: replace ${GITHUB_TOKEN} with your PAT

# 3. Install
npm install -g @bandersnatch0x/amber-protocol
amber --version

Other @bandersnatch0x/* packages (if any are added as dependencies) will also resolve from GitHub Packages automatically.

For CI (GitHub Actions), secrets.GITHUB_TOKEN is available automatically — the publish workflow (.github/workflows/publish-github-packages.yml) builds the .npmrc on the fly.

Quick Start

Bring Amber into an existing repository and produce a handoff-ready delivery bundle:

# 1. Read-only audit of the target repo (changes nothing)
amber audit --target my-project --summary

# 2. Install Amber starter files (skips anything that already exists)
amber init --target my-project

# 3. Verify the repo now has the expected agent-facing surfaces
amber doctor --target my-project

# 4. Score the delivery loop and risks
amber governance report --target my-project

# 5. Ask Amber what to do next: it reads live state and prints one command
amber next --target my-project

# 6. Produce and validate the portable handoff bundle
amber handoff bundle --target my-project
amber handoff validate --target my-project

init and wiki never overwrite existing files. See the CLI reference for the full command surface.

amber governance report - readiness score and next actions

amber governance report is the primary product-loop report. It scores governance, evidence, continuity, safety, and maintenance; names risks; and emits structured next actions with the exact command and expected outcome.

amber governance report --target .
amber governance report --target . --output docs/quality/amber-governance-report.md

amber workflow — workflow effectiveness (ADR-0008)

amber workflow is a separate read-only assessment from governance readiness. It scores five Amber dimensions (Context Adequacy, Lifecycle Discipline, Verification Coverage, Delivery Integrity, Improvement Loop) from repository evidence and optional session observations. Diagnostics go to stderr; stdout stays parser-safe JSON (or Markdown). Never merges into readiness's overall score.

# Assess the target (stdout JSON; sessions included by default)
amber workflow assess --target .
amber workflow assess --target . --format markdown
amber workflow assess --target . --output-dir .amber/workflow-reports
amber workflow assess --target . --no-sessions

# Operate on a saved report
amber workflow findings --target . --report path/to/report.json
amber workflow plan --target . --report path/to/report.json --finding ca-1-feature-observable
amber workflow compare --target . --baseline path/to/old.json --current path/to/new.json

plan is dry-run only (plan-input or maintenance-proposal draft). Only assess accepts --output-dir. Full flag list: CLI reference — Workflow Commands.

amber handoff bundle - portable continuation artifact

amber handoff bundle writes a complete handoff directory with the session summary, verification evidence, risks, next actions, recovery commands, and manifest. handoff validate checks that the bundle is complete before another human or agent continues.

amber handoff bundle --target .
amber handoff validate --target .

amber next — guided next step

amber next is read-only: it infers where the repo sits in the Amber delivery lifecycle (init → feature → plan → gate → verify/approve → complete-check → accept) and prints the single most relevant next command — it never runs anything itself.

amber next --target .                 # auto-selects a focus and states which it chose
amber next --target . --feature F001  # focus one feature's lifecycle
amber next --target . --session <id>  # focus a session's verify → approve → complete-check
amber next --target . --json          # machine-readable envelope (focus, nextStep, remedy)

When a focus is omitted, next picks the active session, else the most-recently-touched plan's feature, else the first unstarted feature — and always says which it chose plus how many other items are pending. The same actionable remedy hints surface inline in doctor checks and review findings, so a failed check tells you the exact command to fix it.

amber loop recommend — safe continuous improvement

amber loop recommend is read-only: it scans local workflow-pack loop contracts, scores them against a maintenance goal, and prints the safest dry-run command to review next. It does not schedule jobs, execute workflow steps, dispatch agents, or write external systems.

amber loop recommend --target . --goal "continuous improvement" --json
amber loop run --file workflow-packs/safe-amber-bootstrap.pack.json --contract daily-amber-triage --dry-run --json

Live scheduling remains outside the current product boundary; loop run requires --dry-run.

Loop Engineering companion

Amber provides the governance and contract layer (loop contracts, ledgers, hard stops, review gates, skills harness). Pair it with the loop-engineering patterns and CLIs for operational readiness:

• npx @cobusgreyling/loop-audit . --suggest — scores loop readiness (L1/L2/L3) and gives concrete suggestions
• npx @cobusgreyling/loop-cost — token/cost estimation before scheduling
• LOOP.md (this repo) — describes Amber's active loops using loop-engineering vocabulary
• Simple STATE.md (optional overlay) — human + agent friendly memory spine compatible with daily-triage etc.

See LOOP.md for Amber's self-described loops (Daily Amber Triage, CI validation, adoption flows) and how the two systems complement each other. Phased rollout (report → assisted → governed) is encouraged.

Mechanical enforcement (opt-in)

Amber's gates are advisory by default — a markdown field someone flips. To enforce them at commit time, install the opt-in guard:

amber hooks install --target .     # writes .git/hooks/pre-commit (opt-in; never auto-installed)
amber hooks status --target .
amber hooks check --target .       # what the hook runs; exits non-zero on a violation

The guard reads governance metadata only (e.g. a feature must not be marked complete with an empty evidence array) — it never runs your build or tests. Install with --warn-only to surface findings without blocking, bypass once with AMBER_SKIP_HOOKS=1 git commit ..., or remove it with amber hooks uninstall.

Every blocking error carries a stable code (e.g. AMBER_E_FEATURE_NO_EVIDENCE). Run amber explain <code> for its cause and fix, amber explain to list them all, or amber explain --markdown docs/ERROR_CODES.md to write a standalone reference table.

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	Minimal — Amber avoids becoming a general execution runtime or live agent platform.	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
• .workflow/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 — see "Governed loop execution" below for the one gated exception
• No scheduled / cron / hook-triggered execution
• No external writes (PRs, issue trackers, notifications) or agent tool-call interception
• No automatic rewrite of existing project docs

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.

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.

Documentation

Topic	Link
Full CLI reference	docs/CLI_REFERENCE.md
Getting started guide	docs/user-guide/getting-started.md
Architecture & governance model	docs/architecture/governance-model.md
Deployment & ops	docs/DEPLOYMENT.md
Monitoring / notifications / policy	MONITORING_SETUP.md · NOTIFICATION_SETUP.md · POLICY_CONFIGURATION.md
Troubleshooting	docs/TROUBLESHOOTING.md
Full docs index	docs/README.md
Spec & roadmap	SPEC.md · ROADMAP.md
Contributing	CONTRIBUTING.md

The web viewer (apps/web) provides a dashboard for sessions and timelines:

cd apps/web
npm install --legacy-peer-deps
npm run dev
# Visit http://localhost:3001

Contributing

See CONTRIBUTING.md for development setup, CI, and the release process.

Support

• 📖 Documentation: docs/
• 🐛 Report bugs: GitHub Issues
• 💡 Feature requests: GitHub Discussions

License

MIT License — see LICENSE for details.

---

Amber Protocol — Repository-local AI coding governance for engineering teams.