Sync

/flow-next:sync is the manual escape hatch for plan-sync.

When planSync.enabled is true, /flow-next:work runs plan-sync automatically on multi-task specs as tasks complete. It is off by default. Use this skill when code changed outside the work loop - manual edits, an external PR, a worker that completed but did not trigger sync - and downstream task specs need to be re-checked against reality.

Not the tracker bridge

/flow-next:sync is plan-sync - internal task-spec reconciliation, documented here. The external tracker bridge that projects a spec to a Linear, GitHub, GitLab, or Jira issue is /flow-next:tracker-sync. The two share a verb and nothing else. See Tracker Sync.

The deterministic tracker CLI is also distinct: flowctl tracker owns external provider operations, while flowctl sync owns local bridge state and receipts. Neither is this plan-sync skill.

Off by default since 4.5.1

Flow-Next runs fully without the automatic pass - which is why it now ships off (earlier installs seeded true; an existing config keeps its value). It costs a reconciliation pass after each completed task, and earns that on specs with dependent tasks whose implementations genuinely drift: opt in with flowctl config set planSync.enabled true, or leave it off and run /flow-next:sync manually when a task invalidates a downstream assumption.

When to use it

• A spec’s later tasks reference paths or APIs that earlier tasks have since renamed.
• A teammate pushed changes that affect a task you have not started yet.
• /flow-next:work ran with plan-sync disabled and you want to catch up.
• You want to preview drift before acting on it.

Invocation

/flow-next:sync <id> [--dry-run]

<id> accepts either id scheme (see Spec & task ids):

• A spec ID (fn-1-add-oauth, legacy fn-1, or a tracker key like wor-17). Syncs all tasks under the spec.
• A task ID (fn-1-add-oauth.2, legacy fn-1.2, or wor-17.2). Syncs that task and its downstream peers.

--dry-run shows what would change without writing.

What it does

For each downstream task, sync compares the task spec against the current state of the codebase and the committed work of upstream tasks. When it finds drift - stale paths, renamed exports, signatures that no longer match - it records the reason and updates the downstream task spec.

Run with --dry-run to preview: the plan-sync agent reports the drift and changes nothing. Without it, the agent updates the downstream task specs and sync reports what changed.

Where it stops

• Not a code change. Sync edits task specs, not implementation files.
• Not a replacement for /flow-next:plan when the spec is fundamentally out of date. If most tasks need regeneration, restart planning.

Worked example

/flow-next:sync fn-14-rate-limits --dry-run

Comparing downstream task specs against current code...
  .2  OK
  .3  DRIFT: references src/export/serializer.ts - renamed to src/export/json.ts in task .1
Dry run: 1 task would be updated. Re-run without --dry-run to apply.

Plan-sync keeps later tasks honest about what earlier tasks actually did to the codebase.

Tips

• Automatic plan-sync is off by default; reach for the manual skill when code changed outside the loop - manual edits, a teammate’s merge.
• --dry-run first on anything surprising; drift reports are cheap, silent spec edits are not.
• Not the tracker bridge: this reconciles internal task specs. Projecting to Linear/GitHub/GitLab/Jira is tracker-sync.

Dynamic usage

Recipes that compose with sync in the cookbook:

• Parallelize - after parallel workers land disjoint tasks, one sync pass re-grounds the remaining queue.
• Team patterns - run it after pulling a teammate’s changes that touch a spec you are mid-way through.

Next step

/flow-next:work <next-ready-task>

Or, if drift surfaced design-level issues, revisit the spec:

/flow-next:plan-review <spec-id>