Standard claim/branch/verify/publish workflow for pod agent sessions. Read this skill at the start of any feature, review, summarize, or meditate session.
This skill covers the shared workflow used by all pod worker agents. Session-specific commands reference this skill rather than duplicating it.
The coordination script handles all GitHub-based multi-agent coordination.
Session UUID is available as $POD_SESSION_ID (exported by pod).
The gh CLI defaults to the current repo, so --repo is not needed.
| Command | What it does |
|---|---|
coordination orient | List unclaimed/claimed issues, open PRs, PRs needing attention |
coordination plan [--label L] "title" | Create GitHub issue with agent-plan + optional label; body from stdin |
coordination create-pr N [--partial] ["title"] | Push branch, create PR closing issue #N, enable auto-merge, swap → . With : adds label. |
claimedhas-pr--partialreplancoordination claim-fix N | Comment on failing PR #N claiming fix (30min cooldown) |
coordination close-pr N "reason" | Comment reason and close PR #N |
coordination list-unclaimed [--label L] | List unclaimed agent-plan issues (FIFO order); optional label filter |
coordination queue-depth [L] | Count of unclaimed issues; optional label for per-type count |
coordination claim N | Claim issue #N — adds claimed label + comment, detects races |
coordination skip N "reason" | Mark claimed issue as needing replan — removes claimed, adds replan label |
coordination add-dep N M | Add depends-on: #M to issue #N's body; adds blocked label if #M is open |
coordination check-blocked | Unblock issues whose depends-on dependencies are all closed |
coordination release-stale-claims [SECS] | Release claimed issues with no PR after SECS seconds (default 4h); manual use only |
coordination lock-planner | Acquire advisory planner lock (20min TTL) |
coordination unlock-planner | Release planner lock early |
Issue lifecycle: planner creates issue (label: agent-plan) →
worker claims it (adds label: claimed) → worker creates PR closing it
(label swaps to has-pr) → auto-merge squash-merges.
Issues marked replan (by skip or partial completion) are handled by the next planner.
Issues with has-pr are excluded from list-unclaimed and queue-depth.
Partial completion: worker uses --partial → label swaps to
replan. A planner creates a new issue for remaining work, then closes
the replan issue with a link to the new one.
Dependencies: Issues can declare depends-on: #N in their body.
coordination plan auto-adds the blocked label if any dependency is
open. check-blocked (run by pod each loop) removes blocked when
all dependencies close. Blocked issues are excluded from
list-unclaimed and queue-depth.
Branch naming: agent/<first-8-chars-of-UUID>
Plan files: plans/<UUID-prefix>.md
Progress files: progress/<UTC-timestamp>_<UUID-prefix>.md
coordination orient
Priority order:
coordination list-unclaimed --label <your-label>
If the queue is empty, write a brief progress note and exit.
coordination claim <issue-number>
If the claim fails (race detected), try the next issue. Read the full issue body:
gh issue view <N> --json body --jq .body
git checkout -b agent/<first-8-chars-of-session-UUID>
git rev-parse HEAD # record starting commit
If the branch already exists (common in reused worktrees): check for an
open PR on it first (gh pr list --head agent/<id>). If a PR exists, create
a new branch with a suffix (agent/<id>-v2). If no PR exists, reset it to