tools-only fn-16-ugn Manual Plan-Sync Trigger
Overview
Add /flow-next:sync command to manually trigger plan-sync from a given task or epic, without requiring the full /flow-next:work loop.
Related: Issue #43
Scope
- New
/flow-next:synccommand (skill) - Reuses existing
agents/plan-sync.md - Works with task ID or epic ID
- Supports
--dry-runflag
Design Notes
Config behavior:
- Manual command ignores
planSync.enabledconfig - if user explicitly runs it, they want it - Auto-trigger in
/flow-next:workstill respects the config
Source task status:
- Any status allowed (todo, in_progress, done, blocked)
- User may have edited spec/code manually - trust their intent
- Differs from auto-trigger which requires
donestatus
Safety:
- Purely additive - doesn't modify existing skills/phases
- Agent works standalone (reads specs + git state, no work-loop context needed)
- Ralph unaffected - calls
/flow-next:workwhich has its own flow
Approach
With task ID (fn-N.M):
- Validate task exists
- Read the task's spec (evidence optional - agent compares spec vs code state)
- Find all downstream
todoorblockedtasks in same epic - If none: report "No downstream tasks to sync" and exit
- Spawn plan-sync agent to update affected specs
With epic ID (fn-N):
- Validate epic exists
- Find all tasks in epic (any status)
- Identify downstream
todoorblockedtasks needing updates - If none: report "No downstream tasks to sync" and exit
- Run plan-sync agent on the full set
With --dry-run:
- Agent shows proposed changes but doesn't write
- Output: "Would update: fn-N.M, fn-N.K" with diff preview
Error Handling
Simple exit + guidance (no complex recovery):
| Case | Message |
|---|---|
No .flow/ directory |
"No .flow/ found. Run flowctl init first." |
| Task/epic not found | "Task fn-X.Y not found. Run flowctl list to see tasks." |
| No downstream tasks | "No downstream tasks to sync (all done or none exist)." |
| Invalid ID format | "Invalid ID format. Use fn-N (epic) or fn-N.M (task)." |
Output
On success, show:
Plan-sync: fn-1.2 → downstream tasks
Scanned: 3 tasks (fn-1.3, fn-1.4, fn-1.5)
Drift detected: 2 tasks
Updated: fn-1.3, fn-1.5
No changes: fn-1.4
Summary: <agent's drift summary>
On dry-run:
Plan-sync: fn-1.2 → downstream tasks (DRY RUN)
Would update:
- fn-1.3: Update API endpoint reference (POST → PUT)
- fn-1.5: Update field name (userId → accountId)
No files modified.
Quick commands
plugins/flow-next/scripts/smoke_test.sh
Acceptance
-
/flow-next:sync fn-N.Mupdates downstream tasks based on source task -
/flow-next:sync fn-Nscans whole epic for drift -
/flow-next:sync fn-N.M --dry-runshows changes without writing - Works with any source task status (not just done)
- Ignores
planSync.enabledconfig (manual = always run) - Includes
blockedtasks in target set (not just todo) - Clear error messages for missing .flow/, invalid ID, no tasks
- Reuses existing plan-sync agent (no duplication)
- Smoke test passes
File Structure
plugins/flow-next/skills/flow-next-sync/
SKILL.md # Main skill (triggers on /flow-next:sync)
References
agents/plan-sync.md- existing agent to reuseskills/flow-next-work/phases.mdsection 3e - current auto-trigger logic- Issue #43 - broader spec-sync feature request