/update-progress kanban board

Install

Install just this, from a clone of the repo. Anything it needs comes with it.

./scripts/install-skills.sh --skill update-progress   # bash, Git Bash, macOS, Linux
.\scripts\install-skills.ps1 -Skill update-progress   # Windows PowerShell

Needs: next (installed with it).

What it does

Takes a handoff document, verifies its claims (git log, tests, code review), then updates the repo's docs, the board and the issue to match what actually happened.

When to use

In a fresh session after session-handoff. The verifier agent runs it end to end.

How to invoke

/update-progress [path to handoff doc]

• Omit the path to use the newest file by mtime in skilleddocs/handoffs/ across all worktrees (then the OS temp dir).
• Claude can also run it itself.

How it works

1. Locate the handoff: the given path, or the newest by mtime.
   • Looks in the handoff folder (AGENTS.md/CLAUDE.md's, else skilleddocs/handoffs/) of every git worktree list entry, current first.
   • In other worktrees, only untracked files.
   • Skips a handoff whose issues already carry a "verified, merged" comment.
   • If several share the newest mtime, it lists them and asks you.
   • If none is found there, it checks the OS temp dir.
2. Verify claims: git log over the handoff's base SHA..head (else git merge-base <default> <branch>).
   • Fetches first. Head counts as merged when it is on origin/<default> or the branch has a merged PR containing it. Squash and rebase merges count. A deleted PR branch is read via the PR's pull/<n>/head ref. A check that errors never counts as merged.
   • Runs the repo's test suite on the handoff's code. It uses the default checkout (fast-forwarded) if head is merged, else the worktree with the branch checked out, else a temporary git worktree add of head.
   • Doesn't trust "tests pass".
3. Code review via the code-review skill if product code changed.
4. Update docs that exist (only once the work is merged into the default branch):
   • Roadmap checkboxes, status doc rows + dated entry, decisions doc (only if a decision was recorded), else README status section / CHANGELOG.md / docs/.
   • Moves a "current phase" marker to where merges are landing.
   • Fixes README feature lists that miss merged capabilities.
   • Never invents doc structure.
5. Update the board: comments on the issue.
   • Closes it and moves the card to Done if complete, verified and merged.
   • Complete and verified but unmerged → In Review with a "verified, awaiting merge" comment.
   • Otherwise sets the card/label to where it stands.
   • Label mode: creates status:done first if missing. When complete, verified and merged, status:in-review (or a never-moved status:in-progress) becomes status:done. Partial or blocked work keeps its label.
6. Escalate deviations: if the handoff's ## Board status lists deviations/innovations, calls consult-plan.
7. Commits the doc edits and the handoff on the default branch.
   • The handoff is moved into the default checkout first if it sits in the task's worktree, so it can't block that branch's next merge.
   • The handoff is committed only if it was left uncommitted and the repo is in commit mode per TRACKING.md.
   • If the default branch is protected, the edits go on a docs/ branch instead (or the repo's own branch prefix). Protected means a PR is required by classic protection or a ruleset. If the answer is unclear (e.g. no admin rights on the classic endpoint), it asks.
   • Pushes, and opens that PR, only on your yes.
8. Ends by calling (or telling you to call) next.

Flow

Card status flow: todo → in-progress → in-review → done.

• todo: set explicitly by gh project item-edit when an issue is added — item-add alone leaves Status empty.
• in-progress: set by pair or meta-orchestrator when they create the branch (their guarded agents can only read with gh).
• in-review: set by session-handoff.
• done: set by update-progress, once verified and merged; unmerged stays in-review.
• Label-mode status:* labels are created on first use (gh label create --color <hex> --force, colors in next/BOARD.md), not assumed to exist.

Design principles

• Every claim is unverified until checked. "Tests pass" in a handoff means nothing until git log and a real test run agree.
• Fresh session. Verification runs in a new context, not the one that did the work.
• Update only what exists. It ticks boxes and adds rows in the docs the repo already has; it never invents doc structure.
• Drift is fixed here. A merged capability missing from the README or status summary gets added, and a "current phase" marker follows where merges land.

Shared context for these principles: Matt Pocock's video.

Use cases

• Closing the loop after /session-handoff: verify, update docs, move the card to Done.
• Checking a handoff someone (or an agent) else wrote before you trust it.
• Inside the verifier agent at the end of each task in a meta-orchestrator run.
• Routing a session's deviations to consult-plan instead of letting them silently change the plan.

Tips

• Run it in a fresh session.
• With no argument it picks the newest file by mtime in the handoff folder of any worktree, so pass the path if several sessions ended recently.
• Only complete, verified and merged work goes to Done and closes the issue.
• Verified but unmerged waits in In Review.
• Anything else is set to where it really stands.
• Code review only runs when product code changed; the verifier agent skips it with review-done=yes.
• It ends with next, so the following task is already on screen.

Example

Related

• Input from session-handoff; calls code-review, consult-plan, next.
• Preloaded by the verifier agent (which can skip step 3 with review-done=yes).

Prereqs

• gh, authenticated with the project OAuth scope: run gh auth refresh -s project -s read:project once (see kanban/README.md).
• consult-plan and next installed.
• A code-review skill for the review step.

Sample workflows

• Close one session, start the next
  session-handoff → you → update-progress → next → you
  Install just this one: ./scripts/install-skills.sh --workflow close-the-loop or .\scripts\install-skills.ps1 -Workflow close-the-loop

Source

• kanban/update-progress/SKILL.md
• kanban/update-progress/README.md