[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6XCBSW1MMEAWEF38VX9NH3E":3,"skill-same:01M6XCBSW1MMEAWEF38VX9NH3E":81},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":39,"linkOnly":40,"markdownContent":41,"markdownBody":42,"frontMatter":43,"refName":44,"commitSha":45,"skillDirectory":46,"forksCount":47,"repositoryHtmlUrl":48,"repositoryHomepageUrl":6,"ownerHtmlUrl":49,"ownerBlogUrl":50,"ownerDescription":51,"updatedAt":52,"install":53,"resources":66},"01M6XCBSW1MMEAWEF38VX9NH3E","workbuddy-guide",null,"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\u002Fonboard a repo, add\u002Fbind a worker, 注册仓库, 加仓库, 接入新仓库, onboard repo, set up worker), explanatory questions (how to use workbuddy, workbuddy guide, teach me workbuddy, 怎么用workbuddy, 使用指南), deployment\u002Frunning\u002Foperating\u002Fdebugging workbuddy, and questions about how issues\u002Ftasks are scheduled or how dependencies between issues work (depends_on, blocked, dependency gate, 依赖, 调度, 排队, '为什么没派发'), and questions about parallel-development workflows (rollouts:N fan-out, synthesize\u002Fsynthesis 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\u002Fscheduling model aren't re-derived from scratch.","Lincyaw\u002Fworkbuddy","Lincyaw","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F53161583?v=4","01M6XC87YTNETZ3AARKMHXJYJR","Aoyang Fang","01M6XC882ZSY5XBX2W6S88AGNH",2,"Apache-2.0","https:\u002F\u002Fgithub.com\u002FLincyaw\u002Fworkbuddy\u002Fblob\u002Fmain\u002Fplugins\u002Fworkbuddy\u002Fskills\u002Fworkbuddy-guide\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38],"workbuddy guide","guide","bind","invoke","scheduled","which","operate","re","coordinator","operating","how to","debugging","worker","deeper","rollouts","up","pick","model","SET","issues","2026-11-10 10:12:30",false,"---\nname: workbuddy-guide\ndescription: \"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\u002Fonboard a repo, add\u002Fbind a worker, 注册仓库, 加仓库, 接入新仓库, onboard repo, set up worker), explanatory questions (how to use workbuddy, workbuddy guide, teach me workbuddy, 怎么用workbuddy, 使用指南), deployment\u002Frunning\u002Foperating\u002Fdebugging workbuddy, and questions about how issues\u002Ftasks are scheduled or how dependencies between issues work (depends_on, blocked, dependency gate, 依赖, 调度, 排队, '为什么没派发'), and questions about parallel-development workflows (rollouts:N fan-out, synthesize\u002Fsynthesis 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\u002Fscheduling model aren't re-derived from scratch.\"\n---\n\n# Workbuddy Guide\n\nA map of what workbuddy is and which command solves which problem. This\nskill is intentionally terse — **for command details always run\n`workbuddy \u003Ccmd> --help`**. The CLI help is the authoritative reference\nand stays in sync with the code; duplicating it here would only drift.\n\n## Bundled references (read when relevant)\n\n- `references\u002Fnew-repo-onboarding.md` — step-by-step checklist for adding a\n  new repo to a workbuddy deployment. Read when setting up a repo.\n- `references\u002Fknown-pitfalls.md` — real-world failure modes and fixes. Read\n  when something misbehaves.\n- `references\u002Fwriting-good-issues.md` — how to write issues that agents can\n  actually process. Read when issues keep failing or getting blocked.\n\n## What workbuddy is\n\nGitHub Issue-driven agent orchestration. Humans file issues with\n`## Acceptance Criteria` and the `workbuddy`+`status:developing` labels;\nworkbuddy polls GitHub, dispatches agents (Claude Code or Codex), and\nreacts to label changes the agents make as they hand off work.\n\nOnly two agent roles exist: **`dev-agent`** and **`review-agent`**.\nRuntime (`claude-code` | `codex`) is a config field, not a separate agent.\n\n```\ndeveloping ⇄ reviewing → done\n   ↕\n blocked  (missing Acceptance Criteria — human fixes, flips back)\n```\n\nDev writes code + PR → flips to `reviewing`. Review evaluates each AC →\n`done` on pass, `developing` on fail (max 3 retries via REQ-055 cap).\n\n## Deployment modes — pick one\n\n| Mode | Command | When to use |\n|------|---------|-------------|\n| **Bundle** (default since v0.5: supervisor + coordinator + worker) | `workbuddy supervisor` + `workbuddy coordinator` + `workbuddy worker` | Production, multi-host, anywhere agent runs must survive worker restarts |\n| **Serve** (single process, legacy) | `workbuddy serve` | Local dev, single-host quick-start; does **not** preserve agents across restart |\n| **Managed install** (systemd) | `workbuddy deploy install` | Long-lived production; defaults to the bundle layout; `deploy redeploy`\u002F`deploy upgrade`\u002F`deploy rollback`\u002F`deploy watch` for updates |\n\nAll three share the same state machine, SQLite store, and agent configs.\nRun `workbuddy \u003Cmode> --help` for flags, `workbuddy deploy install --help`\nfor the systemd wrapper examples. See the `\u002Fdeploy` skill for the bundle\ntopology rationale and the cutover from `serve`.\n\n## Command map — what to reach for\n\nRun `workbuddy --help` for the full list. Grouped by intent:\n\n**Setup a repo**\n- `workbuddy init` — scaffold `.github\u002Fworkbuddy\u002F` in a new repo\n- `workbuddy validate` — sanity-check config before running\n- `workbuddy repo register` — attach a repo to a running coordinator (no restart)\n\n**Run workbuddy**\n- `workbuddy supervisor` + `workbuddy coordinator` + `workbuddy worker` — bundle mode (default)\n- `workbuddy serve` — single-process legacy mode (local dev only)\n- `workbuddy deploy install|redeploy|upgrade|rollback|watch` — managed systemd install\n\n**Observe**\n- `workbuddy status` — issues, tasks, events, stuck issues, or `--watch` until done\n- `workbuddy status --events --since 10m` — audit trail with real RFC3339 timestamps\n  (v0.6.24+ fix); useful event types include the recovery-loop signals\n  `periodic_recovery_tick`, `task_reaped`, `dispatch_skipped_inflight`\n  (with `source` discriminator: `statemachine` \u002F `router` \u002F `resync`),\n  plus the original `state_entry`, `dispatch`, `completed`,\n  `dispatch_blocked_by_dependency`\n- `workbuddy logs \u003Cissue>` — per-attempt session logs (stdout\u002Fstderr\u002Ftool calls)\n- `workbuddy diagnose` — surfaces stuck issues, 3-retry caps, stale claims,\n  and (v0.6.24+) `worker_tunnel_down` findings per registered repo; `--fix`\n  for safe auto-remediation\n- `workbuddy hooks list|status|test|reload` — operator-owned event hooks (Slack\u002FFeishu\u002Fetc.)\n\n**Recover**\n- `workbuddy cache invalidate` — force re-poll after manual label edits (`cache-invalidate` remains as a deprecated alias)\n- `workbuddy issue restart` — clear poller cache + claim lease for one issue (was `admin restart-issue`, now deprecated)\n- `workbuddy recover` — clean stale processes\u002Fworktrees\u002Fclaims after a crash (`--kill-zombies --prune-worktrees --prune-remote-branches --reset-db`)\n- `workbuddy operator-watch` — tail the operator incident inbox and auto-dispatch Claude per incident\n\n**Worker runtime ops**\n- `workbuddy worker repos add|list|remove` — change a running worker's repo bindings without restart\n- `workbuddy coordinator token create|list|revoke` — per-worker auth tokens\n\n## Retry and failure semantics (worth knowing)\n\nThe state machine has several guardrails that change how failures look —\nread the relevant decision docs for depth; the short version:\n\n- **3-retry cap (REQ-055)**: after 3 consecutive agent failures on the same\n  issue, dispatch stops. `workbuddy diagnose` surfaces this explicitly.\n- **Infra vs verdict (REQ-056)**: launcher\u002Fruntime crashes are reported with\n  an \"Infra Error\" comment header and do **not** burn the retry budget. Only\n  agent-decided FAIL verdicts count toward the cap.\n- **Issue-claim with TTL (REQ-057, hardened in REQ-059)**: a SQLite claim\n  prevents two workers from dispatching the same issue concurrently. Stale\n  claims self-heal after TTL expiry.\n- **Worktree isolation (REQ-058)**: every task runs in its own\n  `.workbuddy\u002Fworktrees\u002Fissue-N\u002F`. If worktree setup fails, the worker\n  reports loudly instead of falling back to CWD.\n- **Snapshot resync (REQ-150, v0.6.24)**: every 5 minutes the poller\n  re-emits `EventIssueResynced` for every cached open issue carrying a\n  workflow trigger label. The state machine consults `IsInflight` +\n  `HasAnyActiveTask`; if both guards pass, the issue is re-dispatched.\n  Closes the post-restart silent-stall pattern.\n- **`task_queue` reaper (REQ-151, v0.6.24)**: every 60 seconds the\n  coordinator flips `status='running'` rows with stale heartbeat\n  (default 5 min grace) to `failed`\u002F`exit_code=-2`, emitting\n  `task_reaped`. Unblocks `HasAnyActiveTask` after worker host death.\n- **Periodic recovery sweep (REQ-152, v0.6.24)**: every 60 seconds\n  `PollerManager.recoverAllPeriodically` walks every active repo,\n  re-enters `recoverOrphanedActiveStates`, and emits a\n  `periodic_recovery_tick` event with `{repos_swept, issues_redispatched}`.\n- **Fault-injection hooks (REQ-148\u002F153, build tag `faultinject`)**:\n  six named failpoints (`poller.list_issues.before\u002Fafter`,\n  `wstunnel.send.drop`, `worker.claim_task.before`,\n  `worker.agent_exec.die_mid`, `store.insert_event.busy`) for\n  reproducing silent-stall scenarios. Zero-cost in production builds.\n\nImpact for operators: if `diagnose` says \"failed 3 times in a row\", check\nthe issue's comments — if they're \"Infra Error\", the bug is infrastructure\n(usually runtime\u002Flauncher), not the acceptance criteria. Fix infra and\n`workbuddy cache invalidate` to restart; don't rewrite the issue.\n\n## Dependencies & scheduling\n\nWorkbuddy has no separate \"scheduler\" or DAG runner — scheduling falls\nout of three pieces working together. Knowing them avoids re-deriving\nthis every time:\n\n1. **Polling.** The Coordinator polls each registered repo at\n   `poll_interval` (config.yaml). GitHub label changes drive the state\n   machine; nothing happens between polls. Force one with\n   `workbuddy cache invalidate --repo owner\u002Fname --issue N`.\n2. **Task queue + claim lease.** Eligible issues go into SQLite\n   `task_queue`. Workers long-poll the Coordinator and claim by\n   `claim_token` with a TTL, so two workers can never run the same task\n   concurrently (REQ-057\u002F059). Parallelism is per-worker per-repo —\n   bind multiple workers (or `--repos owner\u002FA=...,owner\u002FB=...`) to fan\n   out across repos.\n3. **Dependency gate.** Declared in the issue **body**, not via labels:\n\n   ````markdown\n   ## Dependencies\n\n   ```yaml\n   workbuddy:\n     depends_on:\n       - \"#26\"\n       - \"Lincyaw\u002Fworkbuddy#27\"\n     ```\n   ````\n\n   The Coordinator parses this every poll, computes a verdict\n   (`ready` \u002F `blocked` \u002F `override` \u002F `needs_human`), and refuses\n   dispatch when blocked, logging a `dispatch_blocked_by_dependency`\n   event. UX signal on GitHub: a single ? reaction added when blocked,\n   removed on unblock. **No managed comment, no resolver agent** — the\n   gate lives entirely in Coordinator Go.\n\n   - Same-repo shorthand `#26` is normalized to `owner\u002Frepo#26`.\n   - `owner\u002Frepo#N` cross-repo refs are accepted but unsupported in v0.1\n     (verdict goes to `needs_human`).\n   - Cycles, malformed refs, or \"trigger label present + depends_on\n     declared but no `status:*` label\" all surface in `workbuddy diagnose`.\n   - Human override: add the `override:force-unblock` label — verdict\n     flips to `override` (treated as ready). Don't toggle `status:blocked`\n     by hand; the Coordinator owns it.\n\n   To see the verdict for one issue:\n   ```bash\n   workbuddy status --repo owner\u002Fname | grep \"  N \"      # CYCLES + DEPENDENCY columns\n   workbuddy status --events --type dispatch_blocked_by_dependency --since 1h\n   ```\n\n   To re-evaluate after editing a dependency declaration:\n   ```bash\n   workbuddy cache invalidate --repo owner\u002Fname --issue N\n   ```\n\nThere is no priority queue, no cron, no time-based scheduling. If you\nwant issue B to wait for issue A, declare it. If you want N tasks in\nparallel, run N workers (or one worker bound to N repos).\n\n## Parallel rollouts + synthesize (per-issue fan-out)\n\nBeyond cross-issue parallelism, **a single issue** can also be developed\nN ways in parallel and then reduced to one PR. This is opt-in per issue.\n\nMental model:\n\n```\n  status:developing  ──fan-out──►  N parallel dev-agent runs\n       (rollouts:N label)            each on its own branch\n                                     workbuddy\u002Fissue-\u003CN>\u002Frollout-K\n                                     each opens its own PR labeled\n                                     rollout:K with \"[rollout K\u002FN]\" title\n                                              │\n                          (≥ join.min_successes succeed)\n                                              ▼\n                                    status:synthesizing\n                                              │\n                                  review-agent runs in mode: synthesize\n                                  → reads all sibling PRs\u002Fbranches\n                                  → emits a structured synthesis_decision:\n                                      • pick one rollout as-is, OR\n                                      • cherry-pick \u002F merge the best\n                                        pieces across siblings into a\n                                        single result branch\n                                              ▼\n                                    status:reviewing\n                                  (normal AC review on the chosen artifact)\n                                              ▼\n                                       status:done\n```\n\nKey points worth knowing:\n\n- Triggered by adding a literal `rollouts:N` label (N in 2..5) to the\n  issue. No label, or `rollouts:1`, takes the legacy single-dev fast\n  path that skips `synthesizing` entirely.\n- Each rollout is a fully isolated dev run — its own worktree, branch,\n  PR, and session — so failures in one rollout don't block siblings.\n  `join.min_successes` (in the workflow YAML) decides when the join\n  fires.\n- The synthesize step is a **reduce**, not a vote. It runs the\n  review-agent in `mode: synthesize`; the agent must return a\n  structured decision (`chosen_rollout_index`, plus optional cherry-pick\n  instructions). If the structured output is malformed, the Coordinator\n  stops the reduce step rather than silently auto-picking — surfaces in\n  the issue as a synthesize failure for human attention.\n- Audit trail: `synthesis_decision` events plus per-rollout sessions\n  visible via the audit\u002Fweb UI (rollout_index\u002Frollouts_total\u002Frollout_group_id).\n- The state graph is in `.github\u002Fworkbuddy\u002Fworkflows\u002Fdefault.md`; the\n  rollout fan-out and `mode: synthesize` are first-class in the\n  workflow YAML, not bolted on.\n\nUse this when the AC admits multiple plausible implementations and you\nwant the agents to explore them in parallel, then keep the best one. For\nstraightforward issues, leave `rollouts:N` off and stick with the\nsingle-dev path.\n\n## Common workflows\n\n**Create a workbuddy issue**\n\n```bash\ngh issue create -R owner\u002Fname \\\n  --title \"…\" \\\n  --body '## Description\n…\n\n## Acceptance Criteria\n- [ ] …' \\\n  --label \"workbuddy,status:developing\"\n```\n\n**Unstick an issue**\n\n```bash\n# Check what's wrong\nworkbuddy diagnose --repo owner\u002Fname\n\n# Manually nudge state and force re-poll\ngh issue edit N -R owner\u002Fname --remove-label status:blocked --add-label status:developing\nworkbuddy cache invalidate --repo owner\u002Fname --issue N\n\n# Or, if the poller cache + claim lease both need clearing (stuck after a crash)\nworkbuddy issue restart --repo owner\u002Fname --issue N \\\n  --coordinator http:\u002F\u002F127.0.0.1:8081 \\\n  --token-file \u002Fhome\u002F$USER\u002F.config\u002Fworkbuddy\u002Fauth-token\n```\n\n**Add a repo to a running deployment** (no restart)\n\n```bash\ncd \u002Fpath\u002Fto\u002Fnew-repo\nworkbuddy repo register --coordinator http:\u002F\u002Fcoord:8081\n# For a worker already running:\nworkbuddy worker repos add owner\u002Fnew-repo=\u002Fpath\u002Fto\u002Fnew-repo\n```\n\n## Environment variables\n\n`workbuddy \u003Ccmd> --help` lists the flags each command honors. Globals that\nmatter across commands:\n\n| Variable | Purpose |\n|----------|---------|\n| `WORKBUDDY_AUTH_TOKEN` | Bearer token for coordinator auth (used with `--auth`) |\n| `WORKBUDDY_SLACK_WEBHOOK_URL` \u002F `WORKBUDDY_FEISHU_WEBHOOK_URL` \u002F `WORKBUDDY_TELEGRAM_*` | Optional notification sinks |\n| `WORKBUDDY_SMTP_*` | Optional email notifications |\n\n## When you need more detail\n\n1. `workbuddy \u003Ccmd> --help` — flags + examples (authoritative)\n2. `references\u002F` in this skill — setup, pitfalls, issue-writing\n3. `docs\u002Fdecisions\u002F` and `docs\u002Fimplemented\u002F` in the repo — architecture rationale\n4. `project-index.yaml` — requirements map (REQ-XXX IDs referenced above)\n\n## Related skills\n\n- `\u002Fsetup-repo` — fully onboard a new repo (labels + config + validation)\n- `\u002Fpipeline-monitor` — watch a running pipeline, diagnose stuck issues\n- `\u002Fmerge-flow` — batch-merge approved workbuddy PRs with conflict handling\n","# Workbuddy Guide\n\nA map of what workbuddy is and which command solves which problem. This\nskill is intentionally terse — **for command details always run\n`workbuddy \u003Ccmd> --help`**. The CLI help is the authoritative reference\nand stays in sync with the code; duplicating it here would only drift.\n\n## Bundled references (read when relevant)\n\n- `references\u002Fnew-repo-onboarding.md` — step-by-step checklist for adding a\n  new repo to a workbuddy deployment. Read when setting up a repo.\n- `references\u002Fknown-pitfalls.md` — real-world failure modes and fixes. Read\n  when something misbehaves.\n- `references\u002Fwriting-good-issues.md` — how to write issues that agents can\n  actually process. Read when issues keep failing or getting blocked.\n\n## What workbuddy is\n\nGitHub Issue-driven agent orchestration. Humans file issues with\n`## Acceptance Criteria` and the `workbuddy`+`status:developing` labels;\nworkbuddy polls GitHub, dispatches agents (Claude Code or Codex), and\nreacts to label changes the agents make as they hand off work.\n\nOnly two agent roles exist: **`dev-agent`** and **`review-agent`**.\nRuntime (`claude-code` | `codex`) is a config field, not a separate agent.\n\n```\ndeveloping ⇄ reviewing → done\n   ↕\n blocked  (missing Acceptance Criteria — human fixes, flips back)\n```\n\nDev writes code + PR → flips to `reviewing`. Review evaluates each AC →\n`done` on pass, `developing` on fail (max 3 retries via REQ-055 cap).\n\n## Deployment modes — pick one\n\n| Mode | Command | When to use |\n|------|---------|-------------|\n| **Bundle** (default since v0.5: supervisor + coordinator + worker) | `workbuddy supervisor` + `workbuddy coordinator` + `workbuddy worker` | Production, multi-host, anywhere agent runs must survive worker restarts |\n| **Serve** (single process, legacy) | `workbuddy serve` | Local dev, single-host quick-start; does **not** preserve agents across restart |\n| **Managed install** (systemd) | `workbuddy deploy install` | Long-lived production; defaults to the bundle layout; `deploy redeploy`\u002F`deploy upgrade`\u002F`deploy rollback`\u002F`deploy watch` for updates |\n\nAll three share the same state machine, SQLite store, and agent configs.\nRun `workbuddy \u003Cmode> --help` for flags, `workbuddy deploy install --help`\nfor the systemd wrapper examples. See the `\u002Fdeploy` skill for the bundle\ntopology rationale and the cutover from `serve`.\n\n## Command map — what to reach for\n\nRun `workbuddy --help` for the full list. Grouped by intent:\n\n**Setup a repo**\n- `workbuddy init` — scaffold `.github\u002Fworkbuddy\u002F` in a new repo\n- `workbuddy validate` — sanity-check config before running\n- `workbuddy repo register` — attach a repo to a running coordinator (no restart)\n\n**Run workbuddy**\n- `workbuddy supervisor` + `workbuddy coordinator` + `workbuddy worker` — bundle mode (default)\n- `workbuddy serve` — single-process legacy mode (local dev only)\n- `workbuddy deploy install|redeploy|upgrade|rollback|watch` — managed systemd install\n\n**Observe**\n- `workbuddy status` — issues, tasks, events, stuck issues, or `--watch` until done\n- `workbuddy status --events --since 10m` — audit trail with real RFC3339 timestamps\n  (v0.6.24+ fix); useful event types include the recovery-loop signals\n  `periodic_recovery_tick`, `task_reaped`, `dispatch_skipped_inflight`\n  (with `source` discriminator: `statemachine` \u002F `router` \u002F `resync`),\n  plus the original `state_entry`, `dispatch`, `completed`,\n  `dispatch_blocked_by_dependency`\n- `workbuddy logs \u003Cissue>` — per-attempt session logs (stdout\u002Fstderr\u002Ftool calls)\n- `workbuddy diagnose` — surfaces stuck issues, 3-retry caps, stale claims,\n  and (v0.6.24+) `worker_tunnel_down` findings per registered repo; `--fix`\n  for safe auto-remediation\n- `workbuddy hooks list|status|test|reload` — operator-owned event hooks (Slack\u002FFeishu\u002Fetc.)\n\n**Recover**\n- `workbuddy cache invalidate` — force re-poll after manual label edits (`cache-invalidate` remains as a deprecated alias)\n- `workbuddy issue restart` — clear poller cache + claim lease for one issue (was `admin restart-issue`, now deprecated)\n- `workbuddy recover` — clean stale processes\u002Fworktrees\u002Fclaims after a crash (`--kill-zombies --prune-worktrees --prune-remote-branches --reset-db`)\n- `workbuddy operator-watch` — tail the operator incident inbox and auto-dispatch Claude per incident\n\n**Worker runtime ops**\n- `workbuddy worker repos add|list|remove` — change a running worker's repo bindings without restart\n- `workbuddy coordinator token create|list|revoke` — per-worker auth tokens\n\n## Retry and failure semantics (worth knowing)\n\nThe state machine has several guardrails that change how failures look —\nread the relevant decision docs for depth; the short version:\n\n- **3-retry cap (REQ-055)**: after 3 consecutive agent failures on the same\n  issue, dispatch stops. `workbuddy diagnose` surfaces this explicitly.\n- **Infra vs verdict (REQ-056)**: launcher\u002Fruntime crashes are reported with\n  an \"Infra Error\" comment header and do **not** burn the retry budget. Only\n  agent-decided FAIL verdicts count toward the cap.\n- **Issue-claim with TTL (REQ-057, hardened in REQ-059)**: a SQLite claim\n  prevents two workers from dispatching the same issue concurrently. Stale\n  claims self-heal after TTL expiry.\n- **Worktree isolation (REQ-058)**: every task runs in its own\n  `.workbuddy\u002Fworktrees\u002Fissue-N\u002F`. If worktree setup fails, the worker\n  reports loudly instead of falling back to CWD.\n- **Snapshot resync (REQ-150, v0.6.24)**: every 5 minutes the poller\n  re-emits `EventIssueResynced` for every cached open issue carrying a\n  workflow trigger label. The state machine consults `IsInflight` +\n  `HasAnyActiveTask`; if both guards pass, the issue is re-dispatched.\n  Closes the post-restart silent-stall pattern.\n- **`task_queue` reaper (REQ-151, v0.6.24)**: every 60 seconds the\n  coordinator flips `status='running'` rows with stale heartbeat\n  (default 5 min grace) to `failed`\u002F`exit_code=-2`, emitting\n  `task_reaped`. Unblocks `HasAnyActiveTask` after worker host death.\n- **Periodic recovery sweep (REQ-152, v0.6.24)**: every 60 seconds\n  `PollerManager.recoverAllPeriodically` walks every active repo,\n  re-enters `recoverOrphanedActiveStates`, and emits a\n  `periodic_recovery_tick` event with `{repos_swept, issues_redispatched}`.\n- **Fault-injection hooks (REQ-148\u002F153, build tag `faultinject`)**:\n  six named failpoints (`poller.list_issues.before\u002Fafter`,\n  `wstunnel.send.drop`, `worker.claim_task.before`,\n  `worker.agent_exec.die_mid`, `store.insert_event.busy`) for\n  reproducing silent-stall scenarios. Zero-cost in production builds.\n\nImpact for operators: if `diagnose` says \"failed 3 times in a row\", check\nthe issue's comments — if they're \"Infra Error\", the bug is infrastructure\n(usually runtime\u002Flauncher), not the acceptance criteria. Fix infra and\n`workbuddy cache invalidate` to restart; don't rewrite the issue.\n\n## Dependencies & scheduling\n\nWorkbuddy has no separate \"scheduler\" or DAG runner — scheduling falls\nout of three pieces working together. Knowing them avoids re-deriving\nthis every time:\n\n1. **Polling.** The Coordinator polls each registered repo at\n   `poll_interval` (config.yaml). GitHub label changes drive the state\n   machine; nothing happens between polls. Force one with\n   `workbuddy cache invalidate --repo owner\u002Fname --issue N`.\n2. **Task queue + claim lease.** Eligible issues go into SQLite\n   `task_queue`. Workers long-poll the Coordinator and claim by\n   `claim_token` with a TTL, so two workers can never run the same task\n   concurrently (REQ-057\u002F059). Parallelism is per-worker per-repo —\n   bind multiple workers (or `--repos owner\u002FA=...,owner\u002FB=...`) to fan\n   out across repos.\n3. **Dependency gate.** Declared in the issue **body**, not via labels:\n\n   ````markdown\n   ## Dependencies\n\n   ```yaml\n   workbuddy:\n     depends_on:\n       - \"#26\"\n       - \"Lincyaw\u002Fworkbuddy#27\"\n     ```\n   ````\n\n   The Coordinator parses this every poll, computes a verdict\n   (`ready` \u002F `blocked` \u002F `override` \u002F `needs_human`), and refuses\n   dispatch when blocked, logging a `dispatch_blocked_by_dependency`\n   event. UX signal on GitHub: a single ? reaction added when blocked,\n   removed on unblock. **No managed comment, no resolver agent** — the\n   gate lives entirely in Coordinator Go.\n\n   - Same-repo shorthand `#26` is normalized to `owner\u002Frepo#26`.\n   - `owner\u002Frepo#N` cross-repo refs are accepted but unsupported in v0.1\n     (verdict goes to `needs_human`).\n   - Cycles, malformed refs, or \"trigger label present + depends_on\n     declared but no `status:*` label\" all surface in `workbuddy diagnose`.\n   - Human override: add the `override:force-unblock` label — verdict\n     flips to `override` (treated as ready). Don't toggle `status:blocked`\n     by hand; the Coordinator owns it.\n\n   To see the verdict for one issue:\n   ```bash\n   workbuddy status --repo owner\u002Fname | grep \"  N \"      # CYCLES + DEPENDENCY columns\n   workbuddy status --events --type dispatch_blocked_by_dependency --since 1h\n   ```\n\n   To re-evaluate after editing a dependency declaration:\n   ```bash\n   workbuddy cache invalidate --repo owner\u002Fname --issue N\n   ```\n\nThere is no priority queue, no cron, no time-based scheduling. If you\nwant issue B to wait for issue A, declare it. If you want N tasks in\nparallel, run N workers (or one worker bound to N repos).\n\n## Parallel rollouts + synthesize (per-issue fan-out)\n\nBeyond cross-issue parallelism, **a single issue** can also be developed\nN ways in parallel and then reduced to one PR. This is opt-in per issue.\n\nMental model:\n\n```\n  status:developing  ──fan-out──►  N parallel dev-agent runs\n       (rollouts:N label)            each on its own branch\n                                     workbuddy\u002Fissue-\u003CN>\u002Frollout-K\n                                     each opens its own PR labeled\n                                     rollout:K with \"[rollout K\u002FN]\" title\n                                              │\n                          (≥ join.min_successes succeed)\n                                              ▼\n                                    status:synthesizing\n                                              │\n                                  review-agent runs in mode: synthesize\n                                  → reads all sibling PRs\u002Fbranches\n                                  → emits a structured synthesis_decision:\n                                      • pick one rollout as-is, OR\n                                      • cherry-pick \u002F merge the best\n                                        pieces across siblings into a\n                                        single result branch\n                                              ▼\n                                    status:reviewing\n                                  (normal AC review on the chosen artifact)\n                                              ▼\n                                       status:done\n```\n\nKey points worth knowing:\n\n- Triggered by adding a literal `rollouts:N` label (N in 2..5) to the\n  issue. No label, or `rollouts:1`, takes the legacy single-dev fast\n  path that skips `synthesizing` entirely.\n- Each rollout is a fully isolated dev run — its own worktree, branch,\n  PR, and session — so failures in one rollout don't block siblings.\n  `join.min_successes` (in the workflow YAML) decides when the join\n  fires.\n- The synthesize step is a **reduce**, not a vote. It runs the\n  review-agent in `mode: synthesize`; the agent must return a\n  structured decision (`chosen_rollout_index`, plus optional cherry-pick\n  instructions). If the structured output is malformed, the Coordinator\n  stops the reduce step rather than silently auto-picking — surfaces in\n  the issue as a synthesize failure for human attention.\n- Audit trail: `synthesis_decision` events plus per-rollout sessions\n  visible via the audit\u002Fweb UI (rollout_index\u002Frollouts_total\u002Frollout_group_id).\n- The state graph is in `.github\u002Fworkbuddy\u002Fworkflows\u002Fdefault.md`; the\n  rollout fan-out and `mode: synthesize` are first-class in the\n  workflow YAML, not bolted on.\n\nUse this when the AC admits multiple plausible implementations and you\nwant the agents to explore them in parallel, then keep the best one. For\nstraightforward issues, leave `rollouts:N` off and stick with the\nsingle-dev path.\n\n## Common workflows\n\n**Create a workbuddy issue**\n\n```bash\ngh issue create -R owner\u002Fname \\\n  --title \"…\" \\\n  --body '## Description\n…\n\n## Acceptance Criteria\n- [ ] …' \\\n  --label \"workbuddy,status:developing\"\n```\n\n**Unstick an issue**\n\n```bash\n# Check what's wrong\nworkbuddy diagnose --repo owner\u002Fname\n\n# Manually nudge state and force re-poll\ngh issue edit N -R owner\u002Fname --remove-label status:blocked --add-label status:developing\nworkbuddy cache invalidate --repo owner\u002Fname --issue N\n\n# Or, if the poller cache + claim lease both need clearing (stuck after a crash)\nworkbuddy issue restart --repo owner\u002Fname --issue N \\\n  --coordinator http:\u002F\u002F127.0.0.1:8081 \\\n  --token-file \u002Fhome\u002F$USER\u002F.config\u002Fworkbuddy\u002Fauth-token\n```\n\n**Add a repo to a running deployment** (no restart)\n\n```bash\ncd \u002Fpath\u002Fto\u002Fnew-repo\nworkbuddy repo register --coordinator http:\u002F\u002Fcoord:8081\n# For a worker already running:\nworkbuddy worker repos add owner\u002Fnew-repo=\u002Fpath\u002Fto\u002Fnew-repo\n```\n\n## Environment variables\n\n`workbuddy \u003Ccmd> --help` lists the flags each command honors. Globals that\nmatter across commands:\n\n| Variable | Purpose |\n|----------|---------|\n| `WORKBUDDY_AUTH_TOKEN` | Bearer token for coordinator auth (used with `--auth`) |\n| `WORKBUDDY_SLACK_WEBHOOK_URL` \u002F `WORKBUDDY_FEISHU_WEBHOOK_URL` \u002F `WORKBUDDY_TELEGRAM_*` | Optional notification sinks |\n| `WORKBUDDY_SMTP_*` | Optional email notifications |\n\n## When you need more detail\n\n1. `workbuddy \u003Ccmd> --help` — flags + examples (authoritative)\n2. `references\u002F` in this skill — setup, pitfalls, issue-writing\n3. `docs\u002Fdecisions\u002F` and `docs\u002Fimplemented\u002F` in the repo — architecture rationale\n4. `project-index.yaml` — requirements map (REQ-XXX IDs referenced above)\n\n## Related skills\n\n- `\u002Fsetup-repo` — fully onboard a new repo (labels + config + validation)\n- `\u002Fpipeline-monitor` — watch a running pipeline, diagnose stuck issues\n- `\u002Fmerge-flow` — batch-merge approved workbuddy PRs with conflict handling\n",{"name":5,"description":7},"main","b9778c800f442939b879c9a556dfb8d6f4a40971","plugins\u002Fworkbuddy\u002Fskills\u002Fworkbuddy-guide",1,"https:\u002F\u002Fgithub.com\u002FLincyaw\u002Fworkbuddy","https:\u002F\u002Fgithub.com\u002FLincyaw","http:\u002F\u002Fprofile.aoyangfang.top\u002F","Student in The Chinese University of Hong Kong, Shenzhen","2026-06-08 13:33:51",{"source":8,"skillName":5,"commands":54,"prompt":64,"zipAvailable":65},[55,58,61],{"tool":56,"command":57},"npx","npx skills add Lincyaw\u002Fworkbuddy --skill workbuddy-guide",{"tool":59,"command":60},"bunx","bunx skills add Lincyaw\u002Fworkbuddy --skill workbuddy-guide",{"tool":62,"command":63},"pnpm","pnpm dlx skills add Lincyaw\u002Fworkbuddy --skill workbuddy-guide","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FLincyaw\u002Fworkbuddy\u002Fblob\u002Fmain\u002Fplugins\u002Fworkbuddy\u002Fskills\u002Fworkbuddy-guide\u002FSKILL.md",true,[67,73,77],{"path":68,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":71,"sourceHtmlUrl":72},"references\u002Fknown-pitfalls.md","REFERENCE","参考文档",13990,"https:\u002F\u002Fgithub.com\u002FLincyaw\u002Fworkbuddy\u002Fblob\u002Fmain\u002Fplugins\u002Fworkbuddy\u002Fskills\u002Fworkbuddy-guide\u002Freferences\u002Fknown-pitfalls.md",{"path":74,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":75,"sourceHtmlUrl":76},"references\u002Fnew-repo-onboarding.md",7442,"https:\u002F\u002Fgithub.com\u002FLincyaw\u002Fworkbuddy\u002Fblob\u002Fmain\u002Fplugins\u002Fworkbuddy\u002Fskills\u002Fworkbuddy-guide\u002Freferences\u002Fnew-repo-onboarding.md",{"path":78,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":79,"sourceHtmlUrl":80},"references\u002Fwriting-good-issues.md",4484,"https:\u002F\u002Fgithub.com\u002FLincyaw\u002Fworkbuddy\u002Fblob\u002Fmain\u002Fplugins\u002Fworkbuddy\u002Fskills\u002Fworkbuddy-guide\u002Freferences\u002Fwriting-good-issues.md",[82,122,149,168,194,215],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":101,"publishedAt":39},"01M6XCBM7B95PB3Q6PHZ3TCM7F","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\u002Fwebui, web\u002F, or the auth\u002Fcookie path.","https:\u002F\u002Fgithub.com\u002FLincyaw\u002Fworkbuddy\u002Fblob\u002Fmain\u002Fplugins\u002Fworkbuddy\u002Fskills\u002Fweb-debug\u002FSKILL.md",[88,93,96],{"categoryNo":89,"categoryName":90,"taxonomyType":91,"taxonomyTypeDesc":92},"01JBSEEDCAT000000000000009","前端开发","SCENARIO","使用场景",{"categoryNo":94,"categoryName":95,"taxonomyType":91,"taxonomyTypeDesc":92},"01JBSEEDCAT000000000000010","后端与接口",{"categoryNo":97,"categoryName":98,"taxonomyType":99,"taxonomyTypeDesc":100},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121],"web","debug","web debug","frontend","auth","browser","harness","api","check","use","webui","spa","end","machine","touch","loads","headless","browser-use","using browser","when",{"skillNo":123,"name":124,"nameZh":6,"description":125,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":126,"categories":127,"keywords":131,"publishedAt":39},"01M6XCBFR925WJSWEYVHGSTT56","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.","https:\u002F\u002Fgithub.com\u002FLincyaw\u002Fworkbuddy\u002Fblob\u002Fmain\u002Fplugins\u002Fworkbuddy\u002Fskills\u002Fsetup-repo\u002FSKILL.md",[128],{"categoryNo":129,"categoryName":130,"taxonomyType":91,"taxonomyTypeDesc":92},"01JBSEEDCAT000000000000023","Skill与智能体开发",[132,133,134,135,136,137,138,139,140,37,141,142,34,143,144,145,146,147,148,121],"setup","setup repo","repo","review","orchestration","workflow","config","dev","repository","configure","initialize","issue","new repo","初始化","canonical","for","labels",{"skillNo":150,"name":151,"nameZh":6,"description":152,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":153,"categories":154,"keywords":155,"publishedAt":39},"01M6XCBAEPZQTAS5FZYCPDEGAG","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.","https:\u002F\u002Fgithub.com\u002FLincyaw\u002Fworkbuddy\u002Fblob\u002Fmain\u002Fplugins\u002Fworkbuddy\u002Fskills\u002Fpipeline-monitor\u002FSKILL.md",[],[156,157,158,159,38,160,110,111,143,161,31,162,163,164,165,27,166,147,167,121],"monitor","pipeline","pipeline monitor","status","supervisor","missed","watch","progress","detect","unit","agent pipeline","single",{"skillNo":169,"name":170,"nameZh":6,"description":171,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":172,"categories":173,"keywords":177,"publishedAt":39},"01M6XCB5RTYNH7QK9RQ5Z4B6NK","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.","https:\u002F\u002Fgithub.com\u002FLincyaw\u002Fworkbuddy\u002Fblob\u002Fmain\u002Fplugins\u002Fworkbuddy\u002Fskills\u002Fmerge-flow\u002FSKILL.md",[174],{"categoryNo":175,"categoryName":176,"taxonomyType":91,"taxonomyTypeDesc":92},"01JBSEEDCAT000000000000015","视觉设计",[178,179,180,181,182,183,38,184,185,186,111,187,188,189,190,44,191,192,193,121],"merge","flow","merge flow","design","validate","report","batch","health","user","integrate","resolve conflicts","conflicts","intent","post","design intent","prs",{"skillNo":195,"name":196,"nameZh":6,"description":197,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":198,"categories":199,"keywords":203,"publishedAt":39},"01M6XCB29F96RJ02Z3BXTAVYSB","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'.","https:\u002F\u002Fgithub.com\u002FLincyaw\u002Fworkbuddy\u002Fblob\u002Fmain\u002Fplugins\u002Fworkbuddy\u002Fskills\u002Fdeploy\u002FSKILL.md",[200],{"categoryNo":201,"categoryName":202,"taxonomyType":91,"taxonomyTypeDesc":92},"01JBSEEDCAT000000000000011","运维与部署",[196,204,205,206,160,207,208,20,111,209,210,31,211,212,213,214,165,27,167,121],"deployment","topology","how","process","install","Legacy","switch","service","as","bundle","serve",{"skillNo":216,"name":217,"nameZh":6,"description":218,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":219,"categories":220,"keywords":221,"publishedAt":39},"01M6XCB0SEG4W4RTFHFGXS7D51","example-skill","This description is intentionally long enough to satisfy the validator reliably.","https:\u002F\u002Fgithub.com\u002FLincyaw\u002Fworkbuddy\u002Fblob\u002Fmain\u002Finternal\u002Fvalidatedocs\u002Ftestdata\u002Fl4-pass\u002F.codex\u002Fskills\u002Fexample-skill\u002FSKILL.md",[],[222,223,224,225],"example skill","example","long","validator"]