PLUGIN brewtools / Skills

deploy — GitHub Actions CI/CD

opus human-invoked

Creates workflows, cuts releases, triggers deployments and watches runs, with a confirmation gate before every write or push. Run it with no arguments: no config yet starts setup, an existing config opens monitor.

Quick reference

FieldValue
Command/brewtools:deploy
Arguments[prompt] [setup|create|release|deploy|monitor|update-agent]
Modelopus
ConfigCLAUDE.local.md (gitignored)
Agentdeploy-admin

Modes

ModeDoes
setupDetect repo, list workflows and secrets, write config, generate deploy-admin
createGenerate workflow YAML from a template (Build+GHCR, Deploy VPS, Release, Security Scan)
releaseProbe tooling, plan, confirm, bump, commit + tag + push, watch CI, verify artifact
deployPick a workflow_dispatch workflow, confirm, trigger, watch the run
monitorRecent runs, workflow states, releases, failed-run logs
update-agentRe-discover workflows, regenerate deploy-admin

Example

/brewtools:deploy release patch

The skill probes release tooling, shows the plan, asks for approval, then runs the approved commit, tag and push chain and watches every CI run of the pushed commit.

How it works

  1. Detect mode

    An explicit mode token wins; otherwise keyword hits decide. Conflicts require clarification.

  2. Check environment

    Verifies gh auth, scopes and repo, then loads the GitHub config from CLAUDE.local.md.

  3. Set up (first run)

    Writes the config, gitignores CLAUDE.local.md, generates deploy-admin.

  4. Classify and confirm

    READ and CREATE run freely. MODIFY, SERVICE, DELETE and PRIVILEGE always ask first.

  5. Operate and monitor

    Create, release or deploy runs after approval, then monitor reports run states and failed logs.

Good to know

Every destructive operation requires explicit confirmation. Compound commands are split into individually classified steps.

Local recovery does not undo publication. After the HEAD push the commit is public; after the tag push consumers may have fetched it. Use an approved next patch version rather than moving public history.

Technical details

Release mode: nothing assumed about your repo

Step 0 lists .claude/scripts/*.sh, scripts/, the package.json scripts and Makefile, then records three values, each defaulting to none:

ValueHolds
BUMP_SCRIPTa bump/version script
POST_SCRIPTa post-release/publish script
CHANGELOGCHANGELOG.md or RELEASE-NOTES.md

none is not a failure: the step is skipped or done by hand, and the report says so. Bump and changelog changes are proposed before any write. Verify checks whatever the project publishes (image, package, /version endpoint); nothing published reports “no external artifact to verify”. references/release-best-practices.md holds a worked example to adapt, not commands to run.

Safety classification and templates

Risk classes (READ, CREATE, MODIFY, SERVICE, DELETE, PRIVILEGE) and their gates: deploy-admin safety levels.

TemplateTrigger
Build + Push GHCRtag / branch
Deploy to VPSworkflow_run / workflow_dispatch, release-tag images only, health check, rollback
Releasetag v*.*.*
Security Scanpush / PR, SARIF upload

All templates pin runs-on: ubuntu-24.04. The Deploy template rejects branch-built images before any server copy and logs in to GHCR with the job token over stdin.

Config, SSH integration and limits
  • Config and workflow inventory live in CLAUDE.local.md. Secret names are stored, values are never read or written.
  • VPS targets come from the SSH inventory written by the ssh skill: run /brewtools:ssh setup first.
  • Limits: 2 retries per operation, 15 gh calls per invocation, 30 s per gh command, 15 min for gh run watch.
  • CI runs are matched by the pushed commit’s headSha; unmatched or timed-out runs are reported, never treated as success. Transaction failures keep their nonzero exit and stop later steps; RELEASED is emitted only after every approved step succeeds.
  • Run update-agent after workflow or config changes.
Delegation

For a bounded unit the skill spawns deploy-admin, one per repo or environment, with the six-field brief described in Delegation. Confirmation gates stay in the main conversation; the agent returns exact approval envelopes and runs only the APPROVED ids.

Troubleshooting
IssueFix
gh not installedInstall from https://cli.github.com/
Not authenticated! gh auth login
Insufficient scopes! gh auth login -s repo,workflow,write:packages
Workflow not triggeringCheck the trigger and branch/tag pattern in the YAML
Release CI failed/brewtools:deploy monitor
VPS deploy failed/brewtools:ssh connect to server-name

deploy-admin agent

Handles multi-step release and deploy units.

SSH skill

Server inventory used for VPS targets.

GitHub source

Scripts and workflow templates.

Brewtools overview

All brewtools skills.

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