feat(amp): add ZERO-294 Amp adapter

[spencercharest]

Summary

• Adds an Amp adapter at plugins/zero-amp with an Amp TypeScript plugin and an Agent Skill MCP overlay.
• Adds scripts/build-amp.sh to assemble .amp/plugins/zero.ts, .agents/skills/zero/SKILL.md, embedded .agents/skills/zero/mcp.json, and the runner/context helpers into dist/zero-amp.
• Adds a standalone consumer guide at guides/amp.md and links it from the README Install Zero list.
• Bumps all versioned manifests to 1.4.0 via make minor.

Ticket

ZERO-302 under ZERO-294.

Official references checked

• Amp manual: https://ampcode.com/manual
• Amp Plugin API: https://ampcode.com/manual/plugin-api
• Installed CLI Plugin API docs: amp plugins show-docs
• Amp CLI install: https://ampcode.com/install.sh
• Workspace settings / MCP: https://ampcode.com/news/cli-workspace-settings
• Custom commands migration: https://ampcode.com/news/slashing-custom-commands
• Command palette: https://ampcode.com/news/command-palette

Install/update surfaces

Project install:

git clone https://github.com/officialzeroxyz/zero-plugins.git
cd zero-plugins
./scripts/build-amp.sh
cp -R dist/zero-amp/. /path/to/your/workspace/

Global install:

git clone https://github.com/officialzeroxyz/zero-plugins.git
cd zero-plugins
./scripts/build-amp.sh
mkdir -p ~/.config/amp/plugins ~/.config/amp/zero/hooks ~/.config/agents/skills
cp dist/zero-amp/.amp/plugins/zero.ts ~/.config/amp/plugins/zero.ts
cp dist/zero-amp/.amp/zero/hooks/*.sh ~/.config/amp/zero/hooks/
rm -rf ~/.config/agents/skills/zero
cp -R dist/zero-amp/.agents/skills/zero ~/.config/agents/skills/zero

Update is git pull, rebuild, and repeat the copy step.

Verification

• ./scripts/build-amp.sh
• ./scripts/build-amp.sh --tar /tmp/zero-amp.tar.gz
• make version -> 1.4.0
• jq . on all Amp JSON files.
• TypeScript no-emit check against @ampcode/plugin:

rm -rf /tmp/amp-plugin-check && mkdir -p /tmp/amp-plugin-check
npm --prefix /tmp/amp-plugin-check init -y >/dev/null
npm --prefix /tmp/amp-plugin-check install --silent typescript @types/node @ampcode/plugin >/dev/null
cp plugins/zero-amp/plugins/zero.ts /tmp/amp-plugin-check/zero.ts
node -e "const fs=require('fs'); const p='/tmp/amp-plugin-check/package.json'; const j=JSON.parse(fs.readFileSync(p)); j.type='module'; fs.writeFileSync(p, JSON.stringify(j,null,2));"
cat > /tmp/amp-plugin-check/tsconfig.json <<'JSON'
{"compilerOptions":{"target":"ES2022","module":"NodeNext","moduleResolution":"NodeNext","types":["node"],"strict":true,"noEmit":true,"skipLibCheck":true},"include":["zero.ts"]}
JSON
/tmp/amp-plugin-check/node_modules/.bin/tsc -p /tmp/amp-plugin-check/tsconfig.json

• git diff --check
• Confirmed guides/agent-install.md is not modified.

Docker install/load/hook smoke plus copied-auth Zero loop:

docker run --rm -v "$PWD":/repo -v "$HOME/.zero:/host-zero:ro" -w /repo ubuntu:24.04 bash -lc '
set -euo pipefail
apt-get update >/dev/null
DEBIAN_FRONTEND=noninteractive apt-get install -y curl ca-certificates bash jq >/dev/null
curl -fsSL https://ampcode.com/install.sh | bash >/tmp/amp-install.log 2>&1
export PATH="$HOME/.local/bin:$PATH"
mkdir -p "$HOME/.zero"
cp -R /host-zero/. "$HOME/.zero/"
chmod -R u+rwX "$HOME/.zero"
amp --version
./scripts/build-amp.sh >/dev/null
mkdir -p /tmp/amp-work
cp -R dist/zero-amp/. /tmp/amp-work/
cd /tmp/amp-work
test -f .agents/skills/zero/SKILL.md
test -f .agents/skills/zero/mcp.json
test -f .amp/plugins/zero.ts
test -x .amp/zero/hooks/ensure-runner.sh
jq -e . .agents/skills/zero/mcp.json >/dev/null
.amp/zero/hooks/zero-context.sh | grep -F "Zero is available"
.amp/zero/hooks/ensure-runner.sh >/tmp/ensure.out 2>/tmp/ensure.err
ZERO="$HOME/.zero/runtime/bin/zero"
"$ZERO" auth whoami --json | jq -e .user.id >/dev/null
# then search/get/fetch CDN upload and curl returned URL
'

Observed:

amp=0.0.1781470549-gb446da (released 2026-06-14T20:55:49.000Z, 2h ago)
runId=run_ic6L5_Mi_yNIhcYq3qESX
url=https://cdn.withzero.xyz/LolkTqxW/agent-harness-e2e-amp-docker-20260614233709.txt
payment=0 USDC via mpp on tempo
body=ZERO-302 Amp Docker copied-auth Zero runner check 20260614233709

~/.zero was copied into Docker from the host. No zero review was submitted, per the ZERO-294 test instructions.

E2E status

Draft because a full Amp-agent-driven Zero capability call still needs an authenticated Amp account/API key. In this environment:

• ~/zeroclick/env does not contain AMP_API_KEY.
• amp plugins list/amp plugins exec attempted to load global plugins and failed without an Amp service connection: failed to load global plugins. Unable to connect to https://ampcode.com/.

Verified: current Amp CLI install, package assembly, embedded MCP skill layout, TypeScript plugin compile, runner helper provisioning, copied ~/.zero auth inside Docker, Zero search/get/fetch, and returned CDN file verification.

Proposed guides/agent-install.md notes

Do not apply this text in this PR. This is the proposed runbook section to fold into guides/agent-install.md later.

### Amp

Amp reads project plugins from `.amp/plugins/*.ts` and project skills from `.agents/skills/<name>/SKILL.md`. Amp skills can embed MCP servers by placing `mcp.json` inside the skill directory, so the Zero adapter ships Zero MCP as `.agents/skills/zero/mcp.json` instead of adding it globally to every turn.

Project install:

```bash
git clone https://github.com/officialzeroxyz/zero-plugins.git
cd zero-plugins
./scripts/build-amp.sh
cp -R dist/zero-amp/. /path/to/your/workspace/
```

Global install:

```bash
git clone https://github.com/officialzeroxyz/zero-plugins.git
cd zero-plugins
./scripts/build-amp.sh
mkdir -p ~/.config/amp/plugins ~/.config/amp/zero/hooks ~/.config/agents/skills
cp dist/zero-amp/.amp/plugins/zero.ts ~/.config/amp/plugins/zero.ts
cp dist/zero-amp/.amp/zero/hooks/*.sh ~/.config/amp/zero/hooks/
rm -rf ~/.config/agents/skills/zero
cp -R dist/zero-amp/.agents/skills/zero ~/.config/agents/skills/zero
```

After changing files, restart Amp or run `plugins: reload` from the command palette. Use `amp plugins list` to inspect project plugins when Amp is authenticated.

The Zero Amp plugin wires `session.start` for runner provisioning and `agent.start` for hidden prompt context. It deliberately does not register a blanket `tool.call` handler because Amp request handlers have no neutral ignore result; returning `allow` for non-Zero tools could weaken unrelated policy. Users who want fewer prompts should use Amp's native permissions commands/settings for command trust rules.

Claude-style plugin compatibility and simpler install option

Full Claude Code plugin package support: No. Amp has its own TypeScript/plugin and repo config model. It reads Claude-compatible skills, so the Zero skill body can be reused, but Amp does not install Claude Code .claude-plugin packages as its native plugin artifact.

What this means for users:

• End users should not build the adapter. The consumer path should be a published package or a prebuilt repo-template artifact.

• Preferred full-integration path once published:

  amp plugin install @zeroxyz/amp-zero
  amp plugin update @zeroxyz/amp-zero

  Verify exact Amp plugin command syntax before making this ready.

• If the TypeScript adapter is not worth maintaining, a simpler option is to place the existing Zero skill under .claude/skills/zero or Amp's native skill path and embed the Zero MCP config in the skill. That is likely much lower maintenance, but it drops plugin hooks.

GitHub Releases / no-build install check

Result: No native Gemini-style GitHub Release install path found. Amp's integration is repo/package oriented and can reuse skills/MCP, but I did not verify an Amp command that installs plugin release assets directly from GitHub Releases.

Best no-build consumer path should be one of:

amp plugin install @zeroxyz/amp-zero

if Amp supports package installs for this plugin shape, or a prebuilt repo-template archive users extract into their project.

A GitHub Release asset can remove the need to run scripts/build-amp.sh, but unless Amp gains/has release-asset install semantics it remains a manual download/extract artifact, not a Gemini-style one-command install.

[spencercharest]

Folded into #63 as a matrix entry (amp in plugins/zero/agents.json) — standalone skills (~/.agents/skills, native Amp discovery path) + MCP data. No hooks fragment possible (Amp hooks are TypeScript plugin files, not JSON config); #63's "CLI changes required" notes the file-copy install mode a zero.ts plugin would need, with this branch's plugin as the prototype. The adapter-template work here stays available on this branch if we later ship per-host templates.