deploy
Workbuddy deployment topology guide — explains the 3-unit bundle (supervisor + coordinator + worker), the rolling-restart property, and the cutover from the legacy single-process `serve` install. Use when the user says 'how should I deploy workbuddy', 'install workbuddy as a service', 'switch to bundle', 'rolling restart', '部署 workbuddy', '升级到 bundle'.
- License 许可
- Apache-2.0
- 最近更新
- 2026-06-08
- Stars
- ★ 2
- Forks
- 1
01 前言 Front Matter
- name
- deploy
- description
- Workbuddy deployment topology guide — explains the 3-unit bundle (supervisor + coordinator + worker), the rolling-restart property, and the cutover from the legacy single-process `serve` install. Use when the user says 'how should I deploy workbuddy', 'install workbuddy as a service', 'switch to bundle', 'rolling restart', '部署 workbuddy', '升级到 bundle'.
03 SKILL.md 正文
Deploy
See docs/upgrade-v0.4-to-v0.5.md and workbuddy deploy install --help.
Topology
Workbuddy supports two systemd layouts:
- Bundle (default since v0.5) — three user units. The supervisor
(
Type=notify,KillMode=process,Restart=always) owns the agent subprocesses behind a unix-socket IPC, so the worker can be SIGKILL'd / restarted without killing in-flight Claude or Codex runs. The worker re-attaches over the socket and continuesevents-v1.jsonlfrom the right offset.workbuddy-supervisor.serviceworkbuddy-coordinator.service(After=workbuddy-supervisor.service)workbuddy-worker.service(After=workbuddy-supervisor.service)
- Legacy single-process
serve— oneworkbuddy.service. Preserved for one migration window and for local-dev convenience only. Does not preserve in-flight agent runs across restart.
Greenfield install (recommended)
workbuddy deploy install --scope user \
--working-directory "$PWD" \
--env-file /home/<you>/.config/workbuddy/worker.env \
--coordinator-args=--listen=127.0.0.1:8081 --coordinator-args=--auth \
--worker-args=--coordinator=http://127.0.0.1:8081 \
--worker-args=--token-file=/home/<you>/.config/workbuddy/auth-token \
--worker-args=--repos=OWNER/REPO=$PWD
The --bundle flag is no longer required — it is accepted as a no-op alias
for backwards compatibility with existing scripts.
Cutover from serve to bundle
systemctl --user stop workbuddy.service
systemctl --user disable workbuddy.service
workbuddy deploy delete --name workbuddy --scope user
workbuddy deploy install --scope user --working-directory "$PWD" \
--env-file <env-file> --coordinator-args=... --worker-args=...
workbuddy deploy upgrade (no flags) refuses to silently upgrade a legacy
serve install — it errors with a migration hint. Pass --legacy-serve if
you genuinely want to upgrade the legacy unit in place.
Rolling-restart upgrade
workbuddy deploy upgrade --name workbuddy-worker --version vX.Y.Z
The supervisor stays up across the worker restart, agents keep running, and the new worker re-attaches via the supervisor socket. This is the operational property issue #281 standardized as the default.
Flag detail
This skill is a signpost. For full flag detail use the CLI:
workbuddy deploy install --help
workbuddy deploy upgrade --help
workbuddy deploy uninstall --help
04 同仓库更多 Skills
workbuddy-guide
Explain and operate workbuddy: what it is, which command to reach for, and where to find deeper references. **Trigger whenever the user mentions 'workbuddy' in any context** — including operational requests (register/onboard a repo, add/bind a worker, 注册仓库, 加仓库, 接入新仓库, onboard repo, set up worker), explanatory questions (how to use workbuddy, workbuddy guide, teach me workbuddy, 怎么用workbuddy, 使用指南), deployment/running/operating/debugging workbuddy, and questions about how issues/tasks are scheduled or how dependencies between issues work (depends_on, blocked, dependency gate, 依赖, 调度, 排队, '为什么没派发'), and questions about parallel-development workflows (rollouts:N fan-out, synthesize/synthesis reduce step, cherry-pick, '并行开发', '多个方案', 'rollout'). Invoke this skill before running workbuddy CLI commands so the documented onboarding flow (coordinator register + worker repos add) and the dependency/scheduling model aren't re-derived from scratch.
web-debug
Validate the workbuddy webui (SPA + auth + JSON API) end-to-end on the same machine workbuddy runs on, using browser-use's headless harness. Use when the user says 'verify the frontend', 'test the SPA', 'check dashboard loads', '前端验证', '验下 webui', or after merging changes that touch internal/webui, web/, or the auth/cookie path.
setup-repo
Configure a GitHub repository for workbuddy orchestration — creates labels, the two canonical agent configs (dev + review), workflow definitions, issue templates, and config.yaml. Use when the user says 'set up repo', 'configure repo for workbuddy', 'initialize workbuddy', '配置仓库', '初始化workbuddy', or wants to onboard a new repo.
pipeline-monitor
Monitor the workbuddy agent pipeline, detect stuck issues, zombie processes, and missed redispatches. Works for both the 3-unit bundle (supervisor + coordinator + worker) and single-process `serve`. Use when the user says 'monitor the pipeline', 'check workbuddy status', '监工', '看看跑完了没', or asks to watch issue progress.
merge-flow
Merge a batch of approved workbuddy PRs into main: order them, resolve conflicts against design intent, validate post-merge health, and report. Use when the user asks to 'merge the batch', 'merge approved PRs', 'integrate finished issues', '批量合并', '处理冲突'; or when the merge-agent is invoked.
example-skill
This description is intentionally long enough to satisfy the validator reliably.