| name | sync |
| version | 0.2.0 |
| description | Catch the Backlog board up to what the Spec Kit artifacts prove — move each linked task's status, re-mirror phase acceptance criteria from tasks.md, and record progress notes. Use after working a spec, when the user says "sync the board", "update the kanban from the specs", or when the spec-bridge Stop gate warns a task lags its spec. |
sync — one-way: spec artifacts → Backlog board
Reconciles every linked task to its spec dir's derived state. The direction is absolute:
files are truth, the board is the view. Sync reads the spec dir and writes the Backlog
task (via the backlog CLI only); it must make zero writes inside any spec dir — not
even a touch. If the derivation looks wrong, the fix happens in the spec workflow
(/speckit.*), never by nudging the board.
Precondition gate
- Find the project root (the directory containing
backlog/).
- Run
node ${CLAUDE_PLUGIN_ROOT}/gates/cli.mjs links <root>. Empty array → STOP: nothing is
linked yet — offer the link skill.
Work — the plan command is the backbone
The reconciling edits are computed, not reasoned. Run:
node ${CLAUDE_PLUGIN_ROOT}/gates/cli.mjs plan <root>
It prints, in execution order, the exact backlog task edit commands that reconcile every
linked task — status moves (including honest backwards moves after a regenerated
tasks.md, and Done-eligible → -s Done with a derived final summary, the ONLY path that
moves a linked task to Done), Spec phase: AC add/remove/check/uncheck at correct post-edit
indexes, and one change-only progress note per touched task. An already-reconciled board
prints nothing. plan never executes anything; running the commands is this skill's job.
- Scope — if the user scoped sync to one task/spec, keep only that task's lines
(commands are grouped per task, in queue order).
- Sanity-check the lines — every line must be
backlog task edit <linked-task-id> … and
must never name an AC that doesn't start with Spec phase: (those are human-authored; the
planner is built to leave them alone — a line that touches one is a bug, stop and report).
- Execute verbatim, in order — the order is load-bearing (removals are emitted
highest-index-first; check/uncheck indexes assume the removals and additions already ran).
Do not reorder, dedupe, or "improve" the commands.
- Skipped tasks —
plan reports tasks with a status outside the board's vocabulary on
stderr (# <id>: … not planned). Don't guess — surface them to the user unchanged.
- Strict mode (
.spec-bridge.json has "strictDone": true): the derivation demands
analysis.md in the spec dir with no unresolved CRITICAL findings before Done. If state
output shows analysis.required blocking Done, tell the user to run /speckit.analyze
and save its report as <specDir>/analysis.md — the gate reads artifacts, not chat
output. Resolving a CRITICAL means fixing it in the spec workflow and re-saving the
report, never editing the board.
- Phase-level vocabulary (
.spec-bridge.json has "statusVocabulary"): plan targets
the board's own stage names (see the README's "Phase-level status" contract). If
reviewing is mapped (e.g. "In Review"), an all-checked spec plans to that status and
plan will not emit -s Done — moving to Done is a deliberate act the gate accepts
there; left unmapped, Done-eligible still plans -s 'Done' with the derived final
summary as before.
Output gate
node ${CLAUDE_PLUGIN_ROOT}/gates/cli.mjs plan <root> again — must print nothing for
the tasks you synced (the plan is idempotent; leftover lines mean a command failed).node ${CLAUDE_PLUGIN_ROOT}/gates/cli.mjs check <root> — exit 0, and no warn: line may
name a task you just synced.- One-way contract held:
git status must show no modifications under any spec dir from
this sync (changes under backlog/ are the CLI's doing and expected).
Handing off
Report per task: old → new status and the progress line (both are visible in the executed
commands). Remind the user that the Stop-hook gate keeps enforcing this bridge between
syncs, and that a task the derivation moved to Done stays Done only as long as the spec
artifacts keep proving it.
