# Sync

Source: https://flow-next.dev/skills/sync/

Manually trigger plan-sync to update downstream task specs after implementation drift.

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

`/flow-next:work` runs plan-sync automatically after every task when `planSync.enabled` is true. 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.

`/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](https://flow-next.dev/integrations/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.

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. See [Running Lean](https://flow-next.dev/understand/what-each-layer-costs/).

## 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

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

`<id>` accepts either id scheme (see [Spec & task ids](https://flow-next.dev/reference/spec-schema/#spec-and-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 surfaces the reason and proposes an update.

Plan-sync never silently rewrites a spec. The user always sees the diff and approves it before any write.

## Outcomes

| Result       | Meaning                                                                        |
| ------------ | ------------------------------------------------------------------------------ |
| `clean`      | No drift. Downstream tasks still match reality.                                |
| `drift`      | Proposed updates with reasons. User approves or rejects per file.              |
| `regenerate` | Spec is too far gone to patch cleanly; offer to regenerate the affected tasks. |

## 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

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

```text
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.

* `/flow-next:work` runs this automatically after each task; 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](https://flow-next.dev/integrations/tracker-sync/).

## Dynamic usage

Recipes that compose with sync in the [cookbook](https://flow-next.dev/guides/cookbook/):

* [Parallelize](https://flow-next.dev/guides/cookbook/#parallelize) - after parallel workers land disjoint tasks, one sync pass re-grounds the remaining queue.
* [Team patterns](https://flow-next.dev/guides/cookbook/#team-patterns) - run it after pulling a teammate’s changes that touch a spec you are mid-way through.

## Next step

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

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

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