К основному содержанию
скилл CX Codex

flow-next-sync — скилл для Claude Code и Codex: синхронизация спек

Скилл flow-next-sync обновляет спеки нижестоящих задач, когда код ушёл вперёд: скилл вручную запускает plan-sync и правит todo и blocked задачи.

MIT ★ 730 обновлён 2026-10-29

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next
Открыть на GitHub

Что делает flow-next-sync

Скилл запускает plan-sync по требованию. На вход идёт id задачи вида fn-N-slug.M или спеки fn-N-slug, плюс необязательный флаг --dry-run, если нужен только список правок. Хэндл трекера вроде wor-17 тоже проходит: id разрешает flowctl show.

Сначала скилл читает references/working-rules.md. flowctl лежит внутри плагина, глобально его ставить не нужно: путь берётся из корня плагина, с запасным вариантом .flow/bin/flowctl. В режиме спеки источником дрейфа становится самая свежая задача со статусом done, а если таких нет — in_progress; нижестоящими считаются остальные todo и blocked. Перед запуском агента глоссарий, активные решения и STRATEGY.md выгружаются в отдельный каталог в .flow/tmp/plan-sync.XXXXXX, чтобы поймать переименования терминов и расхождения со стратегией.

Без каталога .flow/ в репозитории работа не начнётся — нужен предварительный flowctl init. Кросс-спековая фаза включается только при planSync.crossSpec=true; без этого флага ручной запуск проверяет задачи одной спеки.

Какие задачи решает

  • подтянуть спеки todo-задач после того, как код разошёлся с планом
  • посмотреть правки plan-sync без записи через --dry-run
  • найти источник дрейфа среди свежих done-задач спеки
  • поймать переименование термина по глоссарию проекта
  • свериться со STRATEGY.md, прежде чем править нижестоящие задачи

Примеры запросов агенту

  • Синхронизируй спеки нижестоящих задач после правок в коде: fn-1-add-oauth.2.
  • Покажи, что plan-sync изменит для fn-1-add-oauth, но без записи — прогон с --dry-run.
  • Реализация ушла от спеки, обнови задачи в статусе todo по wor-17.

Как установить flow-next-sync

1Через маркетплейс плагинов

/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next

Команда ставит плагин flow-next целиком, со всеми его скиллами

2Через Skills CLI (Vercel)

npx skills add gmickel/flow-next --skill flow-next-sync -a claude-code

3Вручную: положить файлы

~/.claude/skills/flow-next-sync/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/flow-next-sync/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о flow-next-sync

Как установить flow-next-sync в Claude Code?

Через маркетплейс плагинов: сначала /plugin marketplace add gmickel/flow-next, затем /plugin install flow-next@flow-next. Скилл приезжает вместе с плагином flow-next.

Что делает flow-next-sync?

Вручную вызывает plan-sync и переписывает спеки нижестоящих задач, которые ещё в статусе todo или blocked. Пригодится, когда код меняется быстрее плана.

Что нужно, чтобы скилл сработал?

Каталог .flow/ в корне репозитория, его создаёт flowctl init. Сам id должен разрешаться через flowctl show, иначе скилл остановится с сообщением о неизвестном id.

Исходный текст

SKILL.md · MIT
---
name: flow-next-sync
description: Manually trigger plan-sync to update downstream task specs after implementation drift. Use when code changes outpace specs.
user-invocable: false
---

# Manual Plan-Sync

Manually trigger plan-sync to update downstream task specs.

Read [working-rules.md](../../references/working-rules.md) first unless you already have this run; it holds for every step of this skill.

## Preamble

**CRITICAL: flowctl is BUNDLED - NOT installed globally.** Define once; subsequent blocks use `$FLOWCTL`:

```bash
FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL="<plugin-root>/scripts/flowctl"   # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"
```

## Input

Arguments: $ARGUMENTS
Format: `<id> [--dry-run]`

- `<id>` - task ID `fn-N-slug.M` (or legacy `fn-N.M`, `fn-N-xxx.M`) or spec ID `fn-N-slug` (or legacy `fn-N`, `fn-N-xxx`), **or a resolvable tracker handle** (`wor-17` / `wor-17.M`) that `flowctl show` maps to the linked spec/task
- `--dry-run` - show changes without writing

## Workflow

### Step 1: Parse Arguments

```bash
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
```

Parse $ARGUMENTS for:
- First positional arg = `ID`
- `--dry-run` flag = `DRY_RUN` (true/false)

**Validate ID first (handle-recognition rule):**
- **The id is resolved by `flowctl show`, not by a prefix check.** A session that rejects a resolvable tracker handle as an unknown id — because it gated on "must start with `fn-`" — has broken this. Route the arg through `$FLOWCTL show <ID> --json` (Step 3); flowctl's widened resolver maps a tracker key (`wor-17` / `wor-17.M`) to its linked spec/task, so a resolvable handle is the existing spec/task, never a new id. `/flow-next:sync wor-17` therefore resolves the linked spec.
- If no ID provided: "Usage: /flow-next:sync <id> [--dry-run]"
- If the arg does not resolve via `flowctl show` (Step 3): "Unknown ID. Use fn-N-slug (spec) / fn-N-slug.M (task), a tracker handle (wor-17), or legacy fn-N, fn-N-xxx."

Detect ID type (use the canonical id from `flowctl show`):
- Contains `.` (e.g., fn-1.2, fn-1-add-oauth.2, wor-17.2) -> task ID
- No `.` (e.g., fn-1, fn-1-add-oauth, wor-17) -> spec ID

### Step 2: Validate Environment

```bash
test -d .flow || { echo "No .flow/ found. Run flowctl init first."; exit 1; }
```

If `.flow/` missing, output error and stop.

### Step 3: Validate ID Exists

```bash
$FLOWCTL show <ID> --json
```

If command fails:
- For task ID: "Task <id> not found. Run `flowctl list` to see available."
- For spec ID: "Spec <id> not found. Run `flowctl specs` to see available."

Stop on failure.

### Step 4: Find Downstream Tasks

**For task ID input:**
```bash
# Extract spec from task ID (remove .N suffix)
SPEC=$(echo "<task-id>" | sed 's/\.[0-9]*$//')

# Get all tasks in spec
$FLOWCTL tasks --spec "$SPEC" --json
```

Filter to `status: todo` or `status: blocked`. Exclude the source task itself.

**For spec ID input:**
```bash
$FLOWCTL tasks --spec "<spec-id>" --json
```

1. First, find a **source task** to anchor drift detection (agent requires `COMPLETED_TASK_IDS`):
   - Prefer most recently updated task with `status: done`
   - Else: most recently updated task with `status: in_progress`
   - Else: error "No completed or in-progress tasks to sync from. Complete a task first."

2. Then filter remaining tasks to `status: todo` or `status: blocked` (these are downstream).

**If no downstream tasks:**
```
No downstream tasks to sync (all done or none exist).
```
Stop here (success, nothing to do).

#### Done when

- A source task is anchored — the input task in task mode, or the most recently updated `done` (else `in_progress`) task in spec mode — or the run stopped with the documented refusal because neither exists.
- `DOWNSTREAM_TASK_IDS` holds the spec's `todo` and `blocked` tasks with the source task excluded. **An empty downstream set stops the run here.** A session that spawns the agent with nothing downstream has broken this.

### Step 5: Gather glossary + decisions + strategy context

Three extra context types help the agent catch drift the spec text alone can't reveal: project-glossary terms (renames where the old spec used a term whose `_Avoid_` alias now appears in code), active decision constraints (current code may touch files mentioned in a decision's `Consequences` section), and strategic-intent drift (completed task contradicts an active `STRATEGY.md` track or approach).

Write the three inputs to files; dispatch only their paths. Empty or failed reads
use the same defaults as an absent source.

```bash
# fence:plan-sync-inputs — FLOWCTL is the resolved executable path
mkdir -p .flow/tmp
SYNC_CONTEXT=$(mktemp -d "$(pwd)/.flow/tmp/plan-sync.XXXXXX") || exit 2
GLOSSARY_JSON_FILE="$SYNC_CONTEXT/glossary.json"
DECISIONS_JSON_FILE="$SYNC_CONTEXT/decisions.json"
STRATEGY_CONTENT_FILE="$SYNC_CONTEXT/strategy.json"
if ! "$FLOWCTL" glossary list --json > "$GLOSSARY_JSON_FILE" 2>/dev/null || [ ! -s "$GLOSSARY_JSON_FILE" ]; then
  printf '%s\n' '{"groups":[],"file_count":0,"total_terms":0}' > "$GLOSSARY_JSON_FILE"
fi
if ! "$FLOWCTL" memory list --track knowledge --category decisions --json > "$DECISIONS_JSON_FILE" 2>/dev/null || [ ! -s "$DECISIONS_JSON_FILE" ]; then
  printf '%s\n' '{"entries":[],"legacy":[],"count":0,"status":"active"}' > "$DECISIONS_JSON_FILE"
fi
if ! "$FLOWCTL" strategy read --json > "$STRATEGY_CONTENT_FILE" 2>/dev/null || [ ! -s "$STRATEGY_CONTENT_FILE" ]; then
  printf '%s\n' '{}' > "$STRATEGY_CONTENT_FILE"
fi
printf '%s\n' "$GLOSSARY_JSON_FILE" "$DECISIONS_JSON_FILE" "$STRATEGY_CONTENT_FILE"
```

Record the printed absolute paths for the dispatch; variables do not persist
across shell calls. The agent reads the files and applies its Phase 3b husk
short-circuit. Keep all three files through the agent's return.

#### Done when

- All three files exist, preserving the empty defaults on failure.
- The dispatch carries file paths, never embedded glossary, decision, or strategy JSON.

### Step 6: Spawn Plan-Sync Agent

Read the cross-spec flag first — the same single config-leaf read `/flow-next:work` performs, so a repo that opted into cross-spec propagation (`planSync.crossSpec=true`) gets the same behavior from a manual `/flow-next:sync` as from the work-loop auto-trigger. Without this, `CROSS_SPEC` is unset and plan-sync skips the cross-spec phase entirely — the tool you reach for after big drift silently checks only same-spec tasks:

```bash
CROSS_SPEC=$($FLOWCTL config get planSync.crossSpec --json | jq -r '.value')
```

Build context and spawn via Task tool:

```
Sync task specs from <source> to downstream tasks.

COMPLETED_TASK_IDS: <source task id - the input task, or selected source for spec mode>
FLOWCTL: <resolved executable path from the preamble>
SPEC_ID: <spec id>
DOWNSTREAM_TASK_IDS: <comma-separated list from step 4>
DRY_RUN: <true|false>
CROSS_SPEC: <the $CROSS_SPEC value read below — literal "true" or "false", NOT "true|false">

GLOSSARY_JSON_FILE: <absolute glossary.json path from step 5>
DECISIONS_JSON_FILE: <absolute decisions.json path from step 5>
STRATEGY_CONTENT_FILE: <absolute strategy.json path from step 5>

<if DRY_RUN is true>
DRY RUN MODE: Report what would change but do NOT use Edit tool. Only analyze and report drift.
</if>
```

Use Task tool with `subagent_type: flow-next:plan-sync`.

**Note:** `COMPLETED_TASK_IDS` is always provided - for task-mode it's the input task, for spec-mode it's the source task selected in Step 4.

#### Done when

- `CROSS_SPEC` was read from `planSync.crossSpec` and passed to the agent as the literal string `true` or `false`.
- **The downstream task-spec edits are made by the spawned `flow-next:plan-sync` agent.** A session that edits downstream task specs directly has broken this.
- Under `--dry-run` the agent is told to report drift without using Edit, and Step 7 closes with "No files modified."

### Step 7: Report Results

After agent returns, format output:

**Normal mode:**
```
Plan-sync: <source> -> downstream tasks

Scanned: N tasks (<list>)
<agent summary>
```

**Dry-run mode:**
```
Plan-sync: <source> -> downstream tasks (DRY RUN)

<agent summary>

No files modified.
```

## Error Messages

| Case | Message |
|------|---------|
| No ID provided | "Usage: /flow-next:sync <id> [--dry-run]" |
| No `.flow/` | "No .flow/ found. Run `flowctl init` first." |
| Unknown ID (does not resolve) | "Unknown ID. Use fn-N-slug (spec) / fn-N-slug.M (task), a tracker handle (wor-17), or legacy fn-N, fn-N-xxx." |
| Task not found | "Task <id> not found. Run `flowctl list` to see available." |
| Spec not found | "Spec <id> not found. Run `flowctl list` to see available." |
| No source (spec mode) | "No completed or in-progress tasks to sync from. Complete a task first." |
| No downstream | "No downstream tasks to sync (all done or none exist)." |

## Rules

- **Ignores config** - `planSync.enabled` setting is for auto-trigger only; manual always runs
- **Any source status** - source task can be todo, in_progress, done, or blocked
- **Includes blocked** - downstream set includes both `todo` and `blocked` tasks
- **Reuses agent** - spawns existing plan-sync agent, no duplication

© Gordon Mickel · MIT · gmickel/flow-next

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
spec-driven habib0x Плагин spec-driven ведёт фичу через три фазы: требования в нотации EARS, дизайн и список задач. Дальше реализацию выполняет агент. CX Codex ★ 1 596звёзд репо openspec-implementation forztf Скилл openspec-implementation для Claude Code последовательно выполняет задачи утверждённых спецификаций OpenSpec, проверяя каждую тестами перед переходом дальше. CX Codex +1 1 400установок add-task NeoLabHQ Скилл add-task создаёт файл задачи в .specs/tasks/draft/ из вашего запроса: с заголовком-действием, типом и исходным текстом. Старт цепочки spec-driven разработки. CX Codex +1 1 300установок ship-learn-next davila7 Превращает транскрипт, статью или туториал в план конкретных действий по циклу Ship-Learn-Next: сделать, осмыслить, спланировать следующий шаг. CX Codex +1 82установок ux-flow-plan jnsahaj Скилл ux-flow-plan помогает составить план архитектуры от сценария пользователя к коду в виде дерева переходов. Пригодится перед рефакторингом или разработкой фичи, чтобы не лезть сразу в детали реализации. CX Codex +1 147установок gsd-next open-gsd Скилл gsd-next для Claude Code и Codex определяет текущее состояние проекта и предлагает меню подходящих следующих действий. Запускается как стартовая точка в рабочих процессах GSD. CX Codex +1 558установок

Из того же набора70

Весь набор →
flow-next-capture Скилл flow-next-capture превращает текущий диалог с агентом в готовую спецификацию .flow/specs/<spec-id>.md через внутреннюю утилиту flowctl без потери договорённостей. CX Codex +1 ★ 730звёзд репо flow-next-prime Скилл flow-next-prime оценивает готовность кодовой базы к работе ИИ-агентов и эксплуатации: проверяет, выполняются ли команды, и выдаёт вердикт с приоритетными следующими шагами. CX Codex +1 ★ 730звёзд репо repo-scout Субагент repo-scout сканирует репозиторий и находит готовые паттерны, конвенции и смежный код перед тем, как агент начнёт писать новую фичу. CX Codex ★ 730звёзд репо flow-next-features Скилл flow-next-features для Claude Code создаёт и обновляет карту пользовательских функций в .flow/features/. QA и drive используют её, чтобы повторно находить маршруты к функциям. CX Codex +1 ★ 730звёзд репо flow-next-visual Скилл flow-next-visual превращает спецификацию, задачу, diff или тему разговора в компактную Markdown-схему. Запустите его, когда длинное объяснение удобнее просмотреть глазами. CX Codex +1 ★ 730звёзд репо flow-next-memory-migrate Скилл flow-next-memory-migrate переносит плоские markdown-файлы заметок в структурированную схему памяти YAML через инструмент flowctl. CX Codex +1 ★ 730звёзд репо flow-next-flow Скилл flow-next-flow для Claude Code и Codex, который маршрутизирует работу между этапами: захват, уточнение, планирование, разработка, QA, создание PR и слияние. Запускается автоматически или в режиме --auto для беспилотных прогонов. CX Codex +1 ★ 730звёзд репо flow-next-chart Скилл flow-next-chart помогает разложить крупную неясную идею на решения и подготовить краткий бриф для захвата в спецификации. Он пригодится, когда сначала нужно понять, что именно предстоит решить. CX Codex +1 ★ 730звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой