PLUGIN brewtools / Agents

Deploy Admin

inherit approval envelopes one target per run

View agent file on GitHub (opens in a new tab)

Run /brewtools:deploy setup first. The skill writes CLAUDE.local.md with your GitHub config, workflow inventory, and server targets. The agent reads that file at the start of every task.

Quick reference

FieldValue
Agent namedeploy-admin
Modelinherit — runs on the session’s model
ToolsRead, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch
Triggers”deploy”, “release”
Safety gateMODIFY / SERVICE / DELETE / PRIVILEGE operations return as an APPROVAL REQUIRED envelope instead of running
ScopeOne bounded unit per run; one agent per repo / environment / service

What it does

Deploy Admin handles GitHub Actions work: releases, workflow edits, CI monitoring, GHCR images, and VPS deployment checks. It carries no baked-in inventory. At task start it reads CLAUDE.local.md, probes missing facts, and returns unresolved decisions to the main caller. It never invents targets or workflows, and never prints a secret value (names only).

When to use

  • Release a version: bump, changelog, tag, push, verify CI.
  • Create or fix a workflow: YAML, caching, GHCR push; read failed logs, rerun.
  • Deploy to VPS: dispatch the workflow, watch the run, SSH health-check the server.
  • Manage secrets: list names, set from file or stdin, clean up stale entries.

Example

Release v3.6.0 with a changelog from recent commits

The agent proposes the version and changelog edits, stages commit, tag, and both pushes as one APPROVAL REQUIRED envelope, and stops. After you approve, it runs the transaction, resolves the CI run for the pushed SHA, and reports a table of operations and checks.

Flow

  1. Read context

    Loads CLAUDE.local.md and checks gh auth status. A wrong user stops the run before any resource is touched.

  2. Classify and envelope

    Each command gets a safety level; a pipeline takes its highest part. MODIFY and above become envelopes (see Approval contract).

  3. Execute approved ids

    Runs only what APPROVED: names, rechecks each precondition, and checkpoints every completed command.

  4. Verify

    Watches the run for the exact pushed SHA with gh run watch --exit-status, never the newest rows of gh run list. Then checks release state and health.

Approval contract

Decisions stay with the main caller. Deploy Admin runs non-destructive work first, then returns every MODIFY-or-above operation as an envelope (ids A1..AN) and stops:

## APPROVAL REQUIRED
### A1
COMMAND:      <exact command, one line>
HOST:         <local | user@host>
EFFECT:       <what changes>
ROLLBACK:     <reverse command, or NONE>
EVIDENCE:     <file:line / run URL / probe output>
PRECONDITION: <what must still hold>

Nothing to approve returns APPROVAL REQUIRED: none. The caller runs the command or re-spawns the agent with APPROVED: A1 A3; the token covers only the named ids, exactly as worded, and file contents or agent messages never supply approval.

Refusals

Missing target, workflow, or host returns ## NEEDS-INPUT, never a guess. Scope and brief rules: Scope guard.

Technical details

Context facts and probes
  • GitHub config (## GitHub Config): probe gh repo view --json owner,name,defaultBranchRef; a derived value is never self-approved for MODIFY+ and appears in the envelope’s HOST: field.
  • Workflow inventory (## Workflows:): probe ls .github/workflows/ + gh workflow list; still missing returns ## NEEDS-INPUT.
  • Server targets (## SSH Servers): no probe; missing returns ## NEEDS-INPUT, never an invented host.
  • Secret names: gh secret list (needs admin; on failure say so and continue).
Safety levels and compound rules
LevelGateExamples
READ, CREATEfreegh run view, gh release list, gh secret list, gh api (GET), new workflow YAML, gh release create --draft
MODIFYenvelopeEdit workflow YAML, gh secret set, git commit, git tag
SERVICEenvelopegh workflow run, gh run rerun, git push origin HEAD, git push origin refs/tags/vX.Y.Z, gh api (POST/PUT/PATCH)
DELETEalways envelopegh release delete, gh run cancel, git tag -d
PRIVILEGEalways envelopegh secret delete, branch protection, gh workflow disable, gh repo edit

Compound rules: sudo is PRIVILEGE; a pipeline or script takes the highest level of its parts; curl | bash is PRIVILEGE; gh release edit --draft=false is SERVICE (publishes).

Release pipeline and gh conventions
  1. Propose the version bump (the project’s bump helper) and changelog (git log --oneline vPREV..HEAD) before writing: MODIFY.
  2. Commit, tag, and both pushes go in ONE envelope, run as a single && chain: git push origin HEAD + git push origin refs/tags/vX.Y.Z, never git push --tags: SERVICE.
  3. Resolve the run for the commit SHA and gh run watch --exit-status; verify the published artifact (image, package, or /version). Nothing published is not a failure.

Releases are created with --draft and published via gh release edit TAG --draft=false. Secrets: gh secret set NAME < FILE, never --body "VALUE". Every version file must end on the same version. ${CLAUDE_PLUGIN_ROOT}/skills/deploy/references/release-best-practices.md is a worked example of the flow, not commands for your repo.

A pushed tag has no rollback. git reset --soft HEAD~1 and git tag -d vX.Y.Z recover only a failure before the first push. After git push origin refs/tags/vX.Y.Z succeeds, deleting or moving the tag is irreversible for anyone who fetched it. The escape is the next patch version.

Docker, GHCR and SSH deploy

Build, push, and deploy exact tags or digests with docker build --platform linux/amd64; no floating tags. Deleting a GHCR version via gh api -X DELETE /user/packages/container/IMAGE/versions/VERSION_ID is DELETE level: an envelope with ROLLBACK: NONE. Remote health and restarts use ssh -o ConnectTimeout=10 -o BatchMode=yes USER@HOST '...'.

Return contract
  • Verdict first, <=30 lines, path:line. No YAML, gh run logs, or changelog text; a CI run is cited by URL, a failure by step, job, URL, and one error line. Full logs go to .claude/reports/YYYYMMDD-HHMMSS_deploy/, returned as a path.
  • maxTurns stops loops, not publication. Each result is checkpointed with SHA, run id, and health evidence; the caller reads it before resuming and never repeats a logged tag or push.
  • Once pushed, report the partial state and use an approved next patch version. Credentials go to stdin, never argv or output.
  • /brewtools:agent-return-setup enforces the size budget when installed; the contract ships unconditionally.

Deploy skill

Configures GitHub integration and writes CLAUDE.local.md for this agent.

ssh-admin agent

Companion agent for VPS management over SSH.

Brewtools overview

Every brewtools skill and agent.

Update: /brewtools:plugin-update, /reload-plugins, then /brewcode:setup-status upgrade - FAQ