flow-next-sync_skill

Overview

This skill lets you manually trigger a plan-sync to update downstream task specs when code changes have introduced implementation drift. It uses the bundled flowctl wrapper and a plan-sync subagent to compare a chosen source task against downstream tasks and either report or apply spec updates. Use it when automated syncs lag behind rapid code changes.

How this skill works

The command parses an ID (task or epic) and optional --dry-run flag, validates the .flow directory and the ID via the bundled flowctl, and locates downstream tasks (todo or blocked) in the same epic. For epic inputs it selects a completed or in-progress source task to anchor drift detection. It then spawns the plan-sync agent with context (COMPLETED_TASK_ID, EPIC_ID, DOWNSTREAM_TASK_IDS, DRY_RUN) and collects the agent summary to produce a concise report. In dry-run mode no edits are made; otherwise the agent may write updated specs.

When to use it

• Code has changed faster than task specs and downstream tasks may be out of date
• You need to re-anchor task specs after merging implementation changes
• When auto plan-sync is disabled or you prefer an explicit, auditable sync
• Before starting work on downstream tasks to ensure specs reflect current code
• When CI or reviewers flag spec drift but automated fixes didn’t run

Best practices

• Always run with the bundled FLOWCTL path provided by the plugin to avoid wrong binaries
• Use --dry-run first to review proposed changes before applying them
• For epic inputs, ensure at least one completed or in-progress task exists to serve as the source
• Run from the repository root so .flow/ detection and flowctl commands work reliably
• Check the agent summary and inspector output before committing any edited specs

Example use cases

• Fix downstream task specs after a refactor that changed API signatures
• Re-anchor an epic after merging a major feature so subsequent tasks get correct context
• Verify what would change using --dry-run during a code review or planning session
• Trigger a sync when automated plan-sync is disabled or failed overnight
• Consolidate multiple small releases by syncing specs to the most recent completed task