[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75X5YC72FAPXD1WBT6RWHQQ":3,"skill-same:01M75X5YC72FAPXD1WBT6RWHQQ":59},{"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":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M75X5YC72FAPXD1WBT6RWHQQ","side-agent",null,"Coordinate split-view main-agent and sub-agent workflows using a shared file-based command queue. Works with ANY CLI IDE that can read\u002Fwrite files and invoke skills. One instance assumes the main-agent role (coordinator); N other instances take on sub-agent roles (workers). Use when the user wants to run a side sub-agent in parallel to the main agent, dispatch research or exploration tasks to sub-agents, poll for sub-agent results, or manage multi-agent split-view sessions. Trigger on \"run side agent\", \"launch sub-agent\", \"main-agent mode\", \"sub-agent mode\", \"split view workflow\", \"coordinate sub-agent\", or when setting up agent-to-agent task delegation.","kingkillery\u002Foh-my-pi","kingkillery","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F200727508?v=4","01M6X59E9Q2FCEGBVQ1P6FT0YC","PK","01M75X46A278QMZ5PC4PH2QYJG",2,"MIT","https:\u002F\u002Fgithub.com\u002Fkingkillery\u002Foh-my-pi\u002Fblob\u002Fmain\u002F.omp\u002Fskills\u002Fside-agent\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: side-agent\ndescription: Coordinate split-view main-agent and sub-agent workflows using a shared file-based command queue. Works with ANY CLI IDE that can read\u002Fwrite files and invoke skills. One instance assumes the main-agent role (coordinator); N other instances take on sub-agent roles (workers). Use when the user wants to run a side sub-agent in parallel to the main agent, dispatch research or exploration tasks to sub-agents, poll for sub-agent results, or manage multi-agent split-view sessions. Trigger on \"run side agent\", \"launch sub-agent\", \"main-agent mode\", \"sub-agent mode\", \"split view workflow\", \"coordinate sub-agent\", or when setting up agent-to-agent task delegation.\n---\n\n# Side-Agent\n\nA file-based multi-agent coordination protocol that works with **any CLI IDE** whose agent can read\u002Fwrite files and invoke skills. No extensions, no IPC, no special APIs — just markdown files and atomic directory\u002Ffile operations on disk. Race-safe on POSIX and Windows.\n\n## Roles\n\n| Role | Count | Responsibility |\n|---|---|---|\n| **Main agent** | exactly 1 | Decomposes work into tasks, dispatches them to the queue, polls for results, mirrors claims into the queue, publishes results, fences stale claims, aggregates, and reports to the user. |\n| **Sub-agent** | 1–N | Polls the queue for unclaimed tasks (read-only), claims one atomically, executes it while renewing a heartbeat, writes a claim-local result + completion marker, then stops touching the claim. Repeats until told to stop. |\n\nThe current agent determines its role at invocation time:\n\n- **`\u002Fside-agent`** (no args, or args describing work) → **main agent**. The current agent becomes the coordinator. It creates the coordination directory, decomposes the work, and instructs the user to launch sub-agent instances.\n- **`\u002Fside-agent join`** → **sub-agent**. The current agent enters the worker loop, polling for tasks from an existing queue.\n\n## Quick start\n\n### Main agent (coordinator)\n\n```\n\u002Fside-agent research the auth module, review the API surface, and write a migration plan\n```\n\nThe agent will:\n1. Create `.side-agent\u002F` in the workspace root (see [PROTOCOL.md](PROTOCOL.md)).\n2. Decompose the work into independent tasks and write them to `queue.md`.\n3. Tell the user exactly how many sub-agent instances to launch and give them the command to run in each.\n4. Poll for results: mirror active claims into the queue, publish completed claim-local results, fence stale claims, and aggregate into a final report.\n\n### Sub-agent (worker)\n\nIn a separate terminal, same workspace:\n\n```\n\u002Fside-agent join\n```\n\nThe agent will:\n1. Read `.side-agent\u002Fsession.md` to confirm a session is active.\n2. Enter a poll loop: scan `queue.md` (read-only) for unclaimed tasks, claim one atomically with an immutable claim token, execute it while renewing the heartbeat, write the result + completion marker into the claim directory, then stop touching the claim.\n3. Stop when the queue is complete and the main agent has signaled completion in `session.md`.\n\n## How it works\n\nAll coordination happens through files in `.side-agent\u002F`:\n\n```\n.side-agent\u002F\n  session.md              — session metadata, lifecycle signal, main heartbeat (main-owned)\n  queue.md                — task queue (main is sole writer of Status and Claimed by)\n  claims\u002F                 — atomic per-task claim locks (one dir per ACTIVE claim)\n    \u003Ctask-id>\u002F\n      claim.md            — Claimed by, Claim token, Claimed at, Heartbeat, Task\n      result.md           — claim-local result (written once by the owning worker)\n      complete            — completion marker, created LAST by the worker\n      events.md           — claim\u002Fworker-local event log (optional)\n  claims-revoked\u002F         — quarantine + audit graveyard for fenced\u002Frecovered claims\n    \u003Ctask-id>-\u003Ctoken>\u002F    — stale\u002Faborted claim moved here atomically by the main agent\n  workers\u002F                — atomic worker-ID registration (one dir per active worker)\n    sub-agent-1\u002F\n      events.md           — worker-local event log (optional)\n  results\u002F                — published results (main-owned)\n    \u003Ctask-id>.md\n  log.md                  — main-owned audit trail (only the main agent appends)\n```\n\nThe protocol is fully specified in [PROTOCOL.md](PROTOCOL.md).\n\nDetailed role instructions:\n- **[MAIN-AGENT.md](MAIN-AGENT.md)** — dispatch, poll, mirror, publish, fence, aggregate, completion\n- **[SUB-AGENT.md](SUB-AGENT.md)** — poll, claim, execute, heartbeat, report, shutdown\n\n## Writer ownership (the key invariants)\n\n- **The main agent is the sole writer of `queue.md` task fields** (`Status`, `Claimed by`) and the **sole appender to `log.md`**. Workers never edit `queue.md` and never append to `log.md` (concurrent appends would interleave\u002Ftear).\n- **Workers write results claim-local.** A worker writes `claims\u002FTASK-\u003Cid>\u002Fresult.md` and creates the `complete` marker last. It never writes under `results\u002F`. The main agent copies the completed `result.md` to `results\u002FTASK-\u003Cid>.md` (write-once) after verifying ownership.\n- **Workers never remove or rename a claim.** Only the main agent fences\u002Fremoves claims.\n\n## Task format\n\nEach task in `queue.md` follows this format:\n\n```markdown\n### TASK-\u003Cid>\n- **Description:** \u003Cwhat to do>\n- **Scope:** \u003Cfiles, packages, or areas to touch>\n- **Deliverable:** \u003Cwhat the result should contain>\n- **Constraints:** \u003Cany restrictions — read-only, no edits, time-box, etc.>\n- **Depends on:** \u003Cnone, or TASK-XXX whose result this task needs>\n- **Status:** pending\n- **Claimed by:** (empty until the main agent mirrors a claim)\n```\n\n## Claim mechanism (atomic + fenced)\n\nOwnership of a task is established by a single **atomic** filesystem operation — creating the task's claim directory such that the create **fails if the directory already exists**. Exactly one caller wins; concurrent attempts fail. The winner then writes an immutable **claim token** into `claim.md`.\n\nTo claim a task:\n\n1. Read `queue.md` (read-only). Find the first task that is `Status: pending` **and** whose dependencies are satisfied (each `results\u002F\u003Cdep>.md` exists **and** its `Status:` is `done`\u002F`partial` — a `failed`\u002Fmissing\u002Fmalformed dependency is not satisfied).\n2. **Atomically create** the directory `.side-agent\u002Fclaims\u002FTASK-\u003Cid>\u002F` so the create fails if it exists: POSIX `mkdir .side-agent\u002Fclaims\u002FTASK-\u003Cid>` (no `-p`); Windows PowerShell `New-Item -ItemType Directory -Path .side-agent\\claims\\TASK-\u003Cid> -ErrorAction Stop`. **Never use cmd.exe `mkdir`** — it returns success on an existing dir on Windows, breaking atomicity.\n3. **Creation succeeded** → you own the task. Generate a fresh immutable claim token; write `claims\u002FTASK-\u003Cid>\u002Fclaim.md` (Claimed by, Claim token, Claimed at, Heartbeat: now, Task). **Do not edit `queue.md`** — the main agent mirrors your claim. Emit a claim event.\n4. **Creation failed because it ALREADY EXISTS** (lost race) → back off: skip to the next pending task; if none, wait 5–15 s jitter and rescan. Do not retry the same create in a tight loop.\n5. **Creation failed for another reason** (parent `claims\u002F` missing, permissions, path-too-long) → not a race. Emit the error, stop, and surface it to the main agent. Do not misclassify it as a lost race or you loop forever.\n\n**Atomic claim invariant:** for any task, at most one worker holds the claim at a time, because ownership is granted by one atomic create. Two workers can never both believe they own the same task, so two workers can never execute the same task. (POSIX `mkdir` fails with EEXIST and PowerShell `New-Item -ErrorAction Stop` throws — both atomic; cmd.exe `mkdir` is not atomic and must be avoided.)\n\n## Heartbeat (renewable, atomic)\n\nWhile executing, the worker renews the `Heartbeat:` field in `claim.md` at least once per minute **and** before\u002Fafter long steps. Each renewal first re-validates ownership (re-read `claim.md`; if the path is gone or the token is no longer yours → revoked, abort), then rewrites `claim.md` via **atomic temp-write+replace**:\n- POSIX: write `claim.md.tmp.\u003Ctoken>` then `mv -f claim.md.tmp.\u003Ctoken> claim.md`\n- PowerShell: write `claim.md.tmp.\u003Ctoken>` then `Move-Item -Force claim.md.tmp.\u003Ctoken> claim.md`\n\n## Fencing (revocation via atomic rename)\n\nThe main agent revokes a stale claim not by deleting it in place, but by **atomically renaming** the whole `claims\u002FTASK-\u003Cid>\u002F` directory into `claims-revoked\u002FTASK-\u003Cid>-\u003Ctoken>`:\n- POSIX: `mv -n .side-agent\u002Fclaims\u002FTASK-001 .side-agent\u002Fclaims-revoked\u002FTASK-001-\u003Ctoken>`\n- PowerShell: `Move-Item -Path .side-agent\\claims\\TASK-001 -Destination .side-agent\\claims-revoked\\TASK-001-\u003Ctoken> -ErrorAction Stop`\n\nThe command exit code alone is not proof (`mv -n` may succeed after skipping). Grant recovery only after verifying source absence, destination presence, and the expected token in the destination `claim.md`; otherwise leave `queue.md` unchanged and rescan.\n\nAfter a successful rename, the original claim path no longer exists, so the old worker's next re-validation fails (path gone) and any write it attempts fails. A fenced worker therefore cannot create the `complete` marker and cannot have its `result.md` published — revoked attempts are ignored. The unique `\u003Ctoken>` suffix means repeated revocations never collide.\n\n## Completion\n\n**Per task (sub-agent):** re-validate ownership → write `claims\u002FTASK-\u003Cid>\u002Fresult.md` (write-once) → create the `complete` marker **last** → stop touching the claim. The worker does not edit `queue.md` and does not remove the claim.\n\n**Per task (main agent):** on seeing `complete` + `result.md`, verify token\u002Fpath\u002Fcurrent ownership → copy `result.md` to `results\u002FTASK-\u003Cid>.md` only if absent (write-once) → set the queue terminal status (`done`\u002F`partial` → `done`; `failed` → `failed`) → archive (move to `claims-revoked\u002F`) or remove the claim. Revoked attempts are ignored.\n\n**Session (main agent):** sets `session.md` `Status: complete` once every task has reached a terminal state (`done` or `failed`) and results are aggregated. Sub-agents see `complete`\u002F`aborted` on their next poll and exit.\n\n## Stale-claim recovery (main agent, fenced)\n\nA worker that crashes mid-task leaves its claim directory behind. On each poll the main agent **scans the contents of `claims\u002F`** (every claim directory present), reconciled against `queue.md` regardless of Status — not only `Status: claimed` rows (this also catches the orphaned-pending case). It is the **only** role that fences\u002Fremoves claim directories it does not own, which prevents two agents racing to recover the same task:\n\n1. For each `claims\u002FTASK-\u003Cid>\u002F` found:\n   - If **both** `complete` marker **and** `result.md` exist → publish (see Completion), then retire the claim. Do not fence a completed claim.\n   - Else if the claim dir has **no `claim.md`** → **initializing**. Leave it alone for a **30-second grace** window. After grace, atomically rename to `claims-revoked\u002F`. **Only if the rename succeeds:** reset to `pending` (clear `Claimed by:`) if not already terminal; log the reclaim. **If the rename fails:** rescan next poll.\n   - Else if `claim.md` exists but its **Heartbeat** is older than the stale threshold (default **5 minutes**) → stalled\u002Fcrashed. Atomically rename to `claims-revoked\u002FTASK-\u003Cid>-\u003Ctoken>`. **Only if the rename succeeds:** reset to `pending` (clear `Claimed by:`) if not already terminal; log `Reclaimed stale TASK-\u003Cid> (was \u003Cclaimer>)`. **If the rename fails:** rescan next poll.\n   - Else (fresh, within threshold) → healthy in-flight; leave it alone.\n\n**Only a verified rename grants recovery.** Confirm source absence, destination presence, and the expected token; a command exit code alone is insufficient. Any failed or ambiguous rename means the main agent rescans rather than changing the queue. There is no immediate reclaim of empty claims and no unfenced in-place deletion.\n\n## Guardrails\n\n- **Main agent does not execute tasks.** It decomposes, dispatches, polls, mirrors claims, publishes results, fences stale claims, and aggregates.\n- **Main agent is the sole writer of `queue.md` task fields and the sole appender to `log.md`.** Workers read `queue.md` read-only and never append to `log.md`.\n- **Sub-agents do not talk to the user.** They write results and events to files only.\n- **Sub-agents must not edit files outside their task scope** unless the task explicitly permits it.\n- **The claim directory plus its claim token are the source of truth for ownership.** `claims\u002FTASK-\u003Cid>\u002Fclaim.md` (not `queue.md`) decides who owns a task; the token is immutable for the claim's life.\n- **Re-validate ownership before any claim.md rewrite and before writing the result.** The worker confirms the path still exists and the token is still its own; if fenced\u002Frevoked, it aborts silently and touches nothing.\n- **Workers never remove or rename a claim directory.** Only the main agent retires (after publishing) or fences (stale recovery) claims.\n- **Worker IDs come from atomic `workers\u002F` dirs**, never from counting `log.md`.\n- **Use portable atomic primitives.** Atomic create: POSIX `mkdir` or PowerShell `New-Item -ErrorAction Stop`; never cmd.exe `mkdir`. Atomic rename (fencing): POSIX `mv -n` or PowerShell `Move-Item -ErrorAction Stop`. Atomic temp-write+replace (heartbeat\u002Fresult): temp file then `mv -f` \u002F `Move-Item -Force`. Classify create failures: already-exists = lost race (back off); anything else = error (stop, surface).\n- **Heartbeat is renewable.** The worker renews `claim.md` `Heartbeat:` ≥ once\u002Fminute and before\u002Fafter long steps (atomic temp-write+replace, after re-validation). The main agent fences claims whose heartbeat is older than 5 minutes.\n- **Empty claims get a 30-second initialization grace**, not immediate reclaim. After grace the main agent fences via atomic rename; only a successful rename resets the task.\n- **Dependencies need a satisfied result.** A dependency is satisfied only when its result exists with `Status:` `done`\u002F`partial`; `failed`\u002Fmissing\u002Fmalformed = not satisfied. The main agent validates the dependency graph is a DAG (no cycles\u002Fself-loops\u002Fdangling) before dispatch.\n- **The queue is append-only for tasks.** Status edits are the main agent's in-place mirror of claim state; `partial` results map to queue `done`.\n- **Results are write-once at both levels.** A worker writes claim-local `result.md` once; the main agent writes `results\u002FTASK-\u003Cid>.md` only when it does not already exist.\n- **Session heartbeat.** The main agent updates `Last heartbeat` every poll; a sub-agent exits if the heartbeat is stale (~2–3 min), so a crashed main agent never leaves workers looping forever.\n- **Jitter is consistently 5–15 s** when no claimable task is available.\n- **Log everything (main-owned).** The main agent appends to `log.md` on every meaningful action; workers emit claim\u002Fworker-local event files which the main agent may fold into the log. This is the audit trail.\n- **Clean up safely.** Only after in-flight claims have drained, the main agent offers to archive (move to `.side-agent-archive\u002F\u003Ctimestamp>\u002F` with a Windows-safe, colon-free timestamp like `2026-07-11T22-00-00Z`) or delete `.side-agent\u002F`. `claims-revoked\u002F` is part of the audit trail.\n","# Side-Agent\n\nA file-based multi-agent coordination protocol that works with **any CLI IDE** whose agent can read\u002Fwrite files and invoke skills. No extensions, no IPC, no special APIs — just markdown files and atomic directory\u002Ffile operations on disk. Race-safe on POSIX and Windows.\n\n## Roles\n\n| Role | Count | Responsibility |\n|---|---|---|\n| **Main agent** | exactly 1 | Decomposes work into tasks, dispatches them to the queue, polls for results, mirrors claims into the queue, publishes results, fences stale claims, aggregates, and reports to the user. |\n| **Sub-agent** | 1–N | Polls the queue for unclaimed tasks (read-only), claims one atomically, executes it while renewing a heartbeat, writes a claim-local result + completion marker, then stops touching the claim. Repeats until told to stop. |\n\nThe current agent determines its role at invocation time:\n\n- **`\u002Fside-agent`** (no args, or args describing work) → **main agent**. The current agent becomes the coordinator. It creates the coordination directory, decomposes the work, and instructs the user to launch sub-agent instances.\n- **`\u002Fside-agent join`** → **sub-agent**. The current agent enters the worker loop, polling for tasks from an existing queue.\n\n## Quick start\n\n### Main agent (coordinator)\n\n```\n\u002Fside-agent research the auth module, review the API surface, and write a migration plan\n```\n\nThe agent will:\n1. Create `.side-agent\u002F` in the workspace root (see [PROTOCOL.md](PROTOCOL.md)).\n2. Decompose the work into independent tasks and write them to `queue.md`.\n3. Tell the user exactly how many sub-agent instances to launch and give them the command to run in each.\n4. Poll for results: mirror active claims into the queue, publish completed claim-local results, fence stale claims, and aggregate into a final report.\n\n### Sub-agent (worker)\n\nIn a separate terminal, same workspace:\n\n```\n\u002Fside-agent join\n```\n\nThe agent will:\n1. Read `.side-agent\u002Fsession.md` to confirm a session is active.\n2. Enter a poll loop: scan `queue.md` (read-only) for unclaimed tasks, claim one atomically with an immutable claim token, execute it while renewing the heartbeat, write the result + completion marker into the claim directory, then stop touching the claim.\n3. Stop when the queue is complete and the main agent has signaled completion in `session.md`.\n\n## How it works\n\nAll coordination happens through files in `.side-agent\u002F`:\n\n```\n.side-agent\u002F\n  session.md              — session metadata, lifecycle signal, main heartbeat (main-owned)\n  queue.md                — task queue (main is sole writer of Status and Claimed by)\n  claims\u002F                 — atomic per-task claim locks (one dir per ACTIVE claim)\n    \u003Ctask-id>\u002F\n      claim.md            — Claimed by, Claim token, Claimed at, Heartbeat, Task\n      result.md           — claim-local result (written once by the owning worker)\n      complete            — completion marker, created LAST by the worker\n      events.md           — claim\u002Fworker-local event log (optional)\n  claims-revoked\u002F         — quarantine + audit graveyard for fenced\u002Frecovered claims\n    \u003Ctask-id>-\u003Ctoken>\u002F    — stale\u002Faborted claim moved here atomically by the main agent\n  workers\u002F                — atomic worker-ID registration (one dir per active worker)\n    sub-agent-1\u002F\n      events.md           — worker-local event log (optional)\n  results\u002F                — published results (main-owned)\n    \u003Ctask-id>.md\n  log.md                  — main-owned audit trail (only the main agent appends)\n```\n\nThe protocol is fully specified in [PROTOCOL.md](PROTOCOL.md).\n\nDetailed role instructions:\n- **[MAIN-AGENT.md](MAIN-AGENT.md)** — dispatch, poll, mirror, publish, fence, aggregate, completion\n- **[SUB-AGENT.md](SUB-AGENT.md)** — poll, claim, execute, heartbeat, report, shutdown\n\n## Writer ownership (the key invariants)\n\n- **The main agent is the sole writer of `queue.md` task fields** (`Status`, `Claimed by`) and the **sole appender to `log.md`**. Workers never edit `queue.md` and never append to `log.md` (concurrent appends would interleave\u002Ftear).\n- **Workers write results claim-local.** A worker writes `claims\u002FTASK-\u003Cid>\u002Fresult.md` and creates the `complete` marker last. It never writes under `results\u002F`. The main agent copies the completed `result.md` to `results\u002FTASK-\u003Cid>.md` (write-once) after verifying ownership.\n- **Workers never remove or rename a claim.** Only the main agent fences\u002Fremoves claims.\n\n## Task format\n\nEach task in `queue.md` follows this format:\n\n```markdown\n### TASK-\u003Cid>\n- **Description:** \u003Cwhat to do>\n- **Scope:** \u003Cfiles, packages, or areas to touch>\n- **Deliverable:** \u003Cwhat the result should contain>\n- **Constraints:** \u003Cany restrictions — read-only, no edits, time-box, etc.>\n- **Depends on:** \u003Cnone, or TASK-XXX whose result this task needs>\n- **Status:** pending\n- **Claimed by:** (empty until the main agent mirrors a claim)\n```\n\n## Claim mechanism (atomic + fenced)\n\nOwnership of a task is established by a single **atomic** filesystem operation — creating the task's claim directory such that the create **fails if the directory already exists**. Exactly one caller wins; concurrent attempts fail. The winner then writes an immutable **claim token** into `claim.md`.\n\nTo claim a task:\n\n1. Read `queue.md` (read-only). Find the first task that is `Status: pending` **and** whose dependencies are satisfied (each `results\u002F\u003Cdep>.md` exists **and** its `Status:` is `done`\u002F`partial` — a `failed`\u002Fmissing\u002Fmalformed dependency is not satisfied).\n2. **Atomically create** the directory `.side-agent\u002Fclaims\u002FTASK-\u003Cid>\u002F` so the create fails if it exists: POSIX `mkdir .side-agent\u002Fclaims\u002FTASK-\u003Cid>` (no `-p`); Windows PowerShell `New-Item -ItemType Directory -Path .side-agent\\claims\\TASK-\u003Cid> -ErrorAction Stop`. **Never use cmd.exe `mkdir`** — it returns success on an existing dir on Windows, breaking atomicity.\n3. **Creation succeeded** → you own the task. Generate a fresh immutable claim token; write `claims\u002FTASK-\u003Cid>\u002Fclaim.md` (Claimed by, Claim token, Claimed at, Heartbeat: now, Task). **Do not edit `queue.md`** — the main agent mirrors your claim. Emit a claim event.\n4. **Creation failed because it ALREADY EXISTS** (lost race) → back off: skip to the next pending task; if none, wait 5–15 s jitter and rescan. Do not retry the same create in a tight loop.\n5. **Creation failed for another reason** (parent `claims\u002F` missing, permissions, path-too-long) → not a race. Emit the error, stop, and surface it to the main agent. Do not misclassify it as a lost race or you loop forever.\n\n**Atomic claim invariant:** for any task, at most one worker holds the claim at a time, because ownership is granted by one atomic create. Two workers can never both believe they own the same task, so two workers can never execute the same task. (POSIX `mkdir` fails with EEXIST and PowerShell `New-Item -ErrorAction Stop` throws — both atomic; cmd.exe `mkdir` is not atomic and must be avoided.)\n\n## Heartbeat (renewable, atomic)\n\nWhile executing, the worker renews the `Heartbeat:` field in `claim.md` at least once per minute **and** before\u002Fafter long steps. Each renewal first re-validates ownership (re-read `claim.md`; if the path is gone or the token is no longer yours → revoked, abort), then rewrites `claim.md` via **atomic temp-write+replace**:\n- POSIX: write `claim.md.tmp.\u003Ctoken>` then `mv -f claim.md.tmp.\u003Ctoken> claim.md`\n- PowerShell: write `claim.md.tmp.\u003Ctoken>` then `Move-Item -Force claim.md.tmp.\u003Ctoken> claim.md`\n\n## Fencing (revocation via atomic rename)\n\nThe main agent revokes a stale claim not by deleting it in place, but by **atomically renaming** the whole `claims\u002FTASK-\u003Cid>\u002F` directory into `claims-revoked\u002FTASK-\u003Cid>-\u003Ctoken>`:\n- POSIX: `mv -n .side-agent\u002Fclaims\u002FTASK-001 .side-agent\u002Fclaims-revoked\u002FTASK-001-\u003Ctoken>`\n- PowerShell: `Move-Item -Path .side-agent\\claims\\TASK-001 -Destination .side-agent\\claims-revoked\\TASK-001-\u003Ctoken> -ErrorAction Stop`\n\nThe command exit code alone is not proof (`mv -n` may succeed after skipping). Grant recovery only after verifying source absence, destination presence, and the expected token in the destination `claim.md`; otherwise leave `queue.md` unchanged and rescan.\n\nAfter a successful rename, the original claim path no longer exists, so the old worker's next re-validation fails (path gone) and any write it attempts fails. A fenced worker therefore cannot create the `complete` marker and cannot have its `result.md` published — revoked attempts are ignored. The unique `\u003Ctoken>` suffix means repeated revocations never collide.\n\n## Completion\n\n**Per task (sub-agent):** re-validate ownership → write `claims\u002FTASK-\u003Cid>\u002Fresult.md` (write-once) → create the `complete` marker **last** → stop touching the claim. The worker does not edit `queue.md` and does not remove the claim.\n\n**Per task (main agent):** on seeing `complete` + `result.md`, verify token\u002Fpath\u002Fcurrent ownership → copy `result.md` to `results\u002FTASK-\u003Cid>.md` only if absent (write-once) → set the queue terminal status (`done`\u002F`partial` → `done`; `failed` → `failed`) → archive (move to `claims-revoked\u002F`) or remove the claim. Revoked attempts are ignored.\n\n**Session (main agent):** sets `session.md` `Status: complete` once every task has reached a terminal state (`done` or `failed`) and results are aggregated. Sub-agents see `complete`\u002F`aborted` on their next poll and exit.\n\n## Stale-claim recovery (main agent, fenced)\n\nA worker that crashes mid-task leaves its claim directory behind. On each poll the main agent **scans the contents of `claims\u002F`** (every claim directory present), reconciled against `queue.md` regardless of Status — not only `Status: claimed` rows (this also catches the orphaned-pending case). It is the **only** role that fences\u002Fremoves claim directories it does not own, which prevents two agents racing to recover the same task:\n\n1. For each `claims\u002FTASK-\u003Cid>\u002F` found:\n   - If **both** `complete` marker **and** `result.md` exist → publish (see Completion), then retire the claim. Do not fence a completed claim.\n   - Else if the claim dir has **no `claim.md`** → **initializing**. Leave it alone for a **30-second grace** window. After grace, atomically rename to `claims-revoked\u002F`. **Only if the rename succeeds:** reset to `pending` (clear `Claimed by:`) if not already terminal; log the reclaim. **If the rename fails:** rescan next poll.\n   - Else if `claim.md` exists but its **Heartbeat** is older than the stale threshold (default **5 minutes**) → stalled\u002Fcrashed. Atomically rename to `claims-revoked\u002FTASK-\u003Cid>-\u003Ctoken>`. **Only if the rename succeeds:** reset to `pending` (clear `Claimed by:`) if not already terminal; log `Reclaimed stale TASK-\u003Cid> (was \u003Cclaimer>)`. **If the rename fails:** rescan next poll.\n   - Else (fresh, within threshold) → healthy in-flight; leave it alone.\n\n**Only a verified rename grants recovery.** Confirm source absence, destination presence, and the expected token; a command exit code alone is insufficient. Any failed or ambiguous rename means the main agent rescans rather than changing the queue. There is no immediate reclaim of empty claims and no unfenced in-place deletion.\n\n## Guardrails\n\n- **Main agent does not execute tasks.** It decomposes, dispatches, polls, mirrors claims, publishes results, fences stale claims, and aggregates.\n- **Main agent is the sole writer of `queue.md` task fields and the sole appender to `log.md`.** Workers read `queue.md` read-only and never append to `log.md`.\n- **Sub-agents do not talk to the user.** They write results and events to files only.\n- **Sub-agents must not edit files outside their task scope** unless the task explicitly permits it.\n- **The claim directory plus its claim token are the source of truth for ownership.** `claims\u002FTASK-\u003Cid>\u002Fclaim.md` (not `queue.md`) decides who owns a task; the token is immutable for the claim's life.\n- **Re-validate ownership before any claim.md rewrite and before writing the result.** The worker confirms the path still exists and the token is still its own; if fenced\u002Frevoked, it aborts silently and touches nothing.\n- **Workers never remove or rename a claim directory.** Only the main agent retires (after publishing) or fences (stale recovery) claims.\n- **Worker IDs come from atomic `workers\u002F` dirs**, never from counting `log.md`.\n- **Use portable atomic primitives.** Atomic create: POSIX `mkdir` or PowerShell `New-Item -ErrorAction Stop`; never cmd.exe `mkdir`. Atomic rename (fencing): POSIX `mv -n` or PowerShell `Move-Item -ErrorAction Stop`. Atomic temp-write+replace (heartbeat\u002Fresult): temp file then `mv -f` \u002F `Move-Item -Force`. Classify create failures: already-exists = lost race (back off); anything else = error (stop, surface).\n- **Heartbeat is renewable.** The worker renews `claim.md` `Heartbeat:` ≥ once\u002Fminute and before\u002Fafter long steps (atomic temp-write+replace, after re-validation). The main agent fences claims whose heartbeat is older than 5 minutes.\n- **Empty claims get a 30-second initialization grace**, not immediate reclaim. After grace the main agent fences via atomic rename; only a successful rename resets the task.\n- **Dependencies need a satisfied result.** A dependency is satisfied only when its result exists with `Status:` `done`\u002F`partial`; `failed`\u002Fmissing\u002Fmalformed = not satisfied. The main agent validates the dependency graph is a DAG (no cycles\u002Fself-loops\u002Fdangling) before dispatch.\n- **The queue is append-only for tasks.** Status edits are the main agent's in-place mirror of claim state; `partial` results map to queue `done`.\n- **Results are write-once at both levels.** A worker writes claim-local `result.md` once; the main agent writes `results\u002FTASK-\u003Cid>.md` only when it does not already exist.\n- **Session heartbeat.** The main agent updates `Last heartbeat` every poll; a sub-agent exits if the heartbeat is stale (~2–3 min), so a crashed main agent never leaves workers looping forever.\n- **Jitter is consistently 5–15 s** when no claimable task is available.\n- **Log everything (main-owned).** The main agent appends to `log.md` on every meaningful action; workers emit claim\u002Fworker-local event files which the main agent may fold into the log. This is the audit trail.\n- **Clean up safely.** Only after in-flight claims have drained, the main agent offers to archive (move to `.side-agent-archive\u002F\u003Ctimestamp>\u002F` with a Windows-safe, colon-free timestamp like `2026-07-11T22-00-00Z`) or delete `.side-agent\u002F`. `claims-revoked\u002F` is part of the audit trail.\n",{"name":5,"description":7},"main","403af0736d24ad919fe5c817fc55f104e6030a8a",".omp\u002Fskills\u002Fside-agent",0,"https:\u002F\u002Fgithub.com\u002Fkingkillery\u002Foh-my-pi","https:\u002F\u002Fgithub.com\u002Fkingkillery","2026-07-30 01:42:39",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add kingkillery\u002Foh-my-pi --skill side-agent",{"tool":37,"command":38},"bunx","bunx skills add kingkillery\u002Foh-my-pi --skill side-agent",{"tool":40,"command":41},"pnpm","pnpm dlx skills add kingkillery\u002Foh-my-pi --skill side-agent","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fkingkillery\u002Foh-my-pi\u002Fblob\u002Fmain\u002F.omp\u002Fskills\u002Fside-agent\u002FSKILL.md",true,[45,51,55],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"MAIN-AGENT.md","REFERENCE","参考文档",10886,"https:\u002F\u002Fgithub.com\u002Fkingkillery\u002Foh-my-pi\u002Fblob\u002Fmain\u002F.omp\u002Fskills\u002Fside-agent\u002FMAIN-AGENT.md",{"path":52,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":53,"sourceHtmlUrl":54},"PROTOCOL.md",26577,"https:\u002F\u002Fgithub.com\u002Fkingkillery\u002Foh-my-pi\u002Fblob\u002Fmain\u002F.omp\u002Fskills\u002Fside-agent\u002FPROTOCOL.md",{"path":56,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":57,"sourceHtmlUrl":58},"SUB-AGENT.md",10578,"https:\u002F\u002Fgithub.com\u002Fkingkillery\u002Foh-my-pi\u002Fblob\u002Fmain\u002F.omp\u002Fskills\u002Fside-agent\u002FSUB-AGENT.md",[60,67,73,80,85,92],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":19},"01M75X7EWZJ876BEFNVJHT1JM0","llm-as-verifier","This skill should be used when the user asks to \"compare candidate patches\", \"rank multiple solutions\", \"choose between implementations\", \"verify two drafts\", \"pick the best trajectory\", \"use llm-as-a-verifier\", or wants repeated criteria-decomposed LLM verification instead of a single free-form judgment.","https:\u002F\u002Fgithub.com\u002Fkingkillery\u002Foh-my-pi\u002Fblob\u002Fmain\u002Fpython\u002Ffugu\u002F.agents\u002Fskills\u002Fllm-as-verifier\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M75X7CVQDM2HJ83G83CJF1CD","pk-subagent-orchestrator","https:\u002F\u002Fgithub.com\u002Fkingkillery\u002Foh-my-pi\u002Fblob\u002Fmain\u002Fpackages\u002Fverifier-extension\u002Fskills\u002Fpk-subagent-orchestrator\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M75X78TNQRB1D04WJMBPYPW6","pk-dynamic-workflows","This skill should be used when the user wants to spawn subagents with different models, configure heterogeneous candidate backends, implement dynamic model routing, or run multi-model fusion workflows. Covers mock, local, premium API (Anthropic\u002FOpenAI), budget API (Kimi\u002FMiniMax\u002FQwen), routing layers (9Router), and CLI backends.","https:\u002F\u002Fgithub.com\u002Fkingkillery\u002Foh-my-pi\u002Fblob\u002Fmain\u002Fpackages\u002Fverifier-extension\u002Fskills\u002Fpk-dynamic-workflows\u002FSKILL.md",[],[],{"skillNo":81,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M75X75C4WSJBJ1YZH0GFJ8E0","https:\u002F\u002Fgithub.com\u002Fkingkillery\u002Foh-my-pi\u002Fblob\u002Fmain\u002Fpackages\u002Fverifier-extension\u002Fskills\u002Fllm-as-verifier\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M75X71TA13A2MQ31KSKPBZ3M","fmh","Run fmh (fusion-meta-harness) — verifier fusion, evaluate-verifier, improve-verifier, promote, run-task. Orchestrates multi-agent candidate generation, rubric scoring, synthesis, and reliability gates for the pi-llm-as-verifier project.","https:\u002F\u002Fgithub.com\u002Fkingkillery\u002Foh-my-pi\u002Fblob\u002Fmain\u002Fpackages\u002Fverifier-extension\u002Fskills\u002Ffmh\u002FSKILL.md",[],[],{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":19},"01M75X70G5YJSGJGBYFVDC4ZMY","greet","A greeting skill for testing","https:\u002F\u002Fgithub.com\u002Fkingkillery\u002Foh-my-pi\u002Fblob\u002Fmain\u002Fpackages\u002Fcoding-agent\u002Ftest\u002Fmarketplace\u002Ffixtures\u002Fvalid-marketplace\u002Fplugins\u002Fhello-plugin\u002Fskills\u002Fgreet\u002FSKILL.md",[],[]]