flow-next-deps — Claude Code skill: spec dependency graph
flow-next-deps shows spec dependency graph, execution order and blocking chains. Use it when you ask 'what's blocking what' or 'what order should specs run'.
MIT ★ 730 updated 2026-10-29
/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-nextWhat flow-next-deps does
The skill builds three reports: which specs are ready, which are blocked and by what, and how to distribute them into parallel execution phases. It runs three steps: gathering all spec data via flowctl show, analyzing blocks in jq, and computing phases. If a spec appears in no phase, it's either a dependency cycle or a reference to a missing or closed spec — the skill lists those separately.
Requires jq and flowctl (bundled with the plugin). Read-only: to change dependencies, use flowctl spec add-dep and rm-dep manually.
What it helps with
- see which specs can start right now
- find the project's critical path
- detect dependency cycles or references to missing specs
- distribute specs into parallel execution phases
Example prompts for the agent
- Show the dependency graph for all specs
- Which specs are blocked and by what?
- Distribute specs into execution phases
How to install flow-next-deps
1Plugin marketplace
/plugin marketplace add gmickel/flow-next/plugin install flow-next@flow-nextThis installs the whole flow-next plugin with all its skills
2Skills CLI (Vercel)
npx skills add gmickel/flow-next --skill flow-next-deps -a claude-code3Manually: put the files in place
~/.claude/skills/flow-next-deps/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/flow-next-deps/
1Skills CLI (Vercel)
npx skills add gmickel/flow-next --skill flow-next-deps -a codex2Manually: put the files in place
.agents/skills/flow-next-deps/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add gmickel/flow-next --skill flow-next-deps -a cursor2Manually: put the files in place
.cursor/skills/flow-next-deps/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install gmickel/flow-next plugins/flow-next/skills/flow-next-deps2Manually: put the files in place
.github/skills/flow-next-deps/SKILL.md1Skills CLI (Vercel)
npx skills add gmickel/flow-next --skill flow-next-deps -a gemini-cli2Platform CLI
gemini skills install https://github.com/gmickel/flow-next --path plugins/flow-next/skills/flow-next-depsManually: put the files in place
.devin/skills/flow-next-deps/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about flow-next-deps
How to install flow-next-deps in Claude Code?
Run /plugin marketplace add gmickel/flow-next, then /plugin install flow-next@flow-next, then npx skills add gmickel/flow-next --skill flow-next-deps -a claude-code. The skill path appears in ~/.claude/skills/flow-next-deps/SKILL.md.
What does flow-next-deps do?
Builds a spec dependency graph: shows which are ready, which are blocked, distributes them into execution phases, and finds cycles or broken references.
What does flow-next-deps require?
Requires jq (install via brew install jq) and flowctl — the script is bundled with the plugin. Without jq, the skill won't run.
Source text
SKILL.md · MIT
---
name: flow-next-deps
description: "Show spec dependency graph and execution order. Use when asking 'what's blocking what', 'execution order', 'dependency graph', 'what order should specs run', 'critical path', 'which specs can run in parallel'."
---
# Flow-Next Dependency Graph
Visualize spec dependencies, blocking chains, and execution phases.
## Preamble
flowctl is bundled with the plugin (not on PATH). 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"
```
## Setup
```bash
$FLOWCTL detect --json | jq -e '.exists' >/dev/null && echo "OK: .flow/ exists" || echo "ERROR: run $FLOWCTL init"
command -v jq >/dev/null 2>&1 && echo "OK: jq installed" || echo "ERROR: brew install jq"
```
## Step 1: Gather Spec Data
Build a consolidated view of all specs with their dependencies — a single heavy per-spec loop for the whole skill. Steps 2 and 3 reuse the cached file (bash vars do not survive across tool calls, so the cache is a file at a literal agent-composed path — compose `<suffix>` once, e.g. 4 random chars, and reuse the same literal path in every later block):
```bash
# ONE gather — Steps 2 and 3 read this file; never re-run the per-spec loop
SPECS_FILE="${TMPDIR:-/tmp}/flow-deps-specs-<suffix>.json"
$FLOWCTL specs --json | jq -r '.specs[].id' | while read id; do
$FLOWCTL show "$id" --json | jq -c '{
id: .id,
title: .title,
status: .status,
plan_review: .plan_review_status,
deps: (.depends_on_epics // [])
}'
done | jq -s '.' > "$SPECS_FILE"
cat "$SPECS_FILE"
```
### Done when
- `$SPECS_FILE` exists at the composed literal path and parses as a JSON array with one object per spec returned by `flowctl specs --json`.
- The per-spec `flowctl show` loop has run exactly once for this invocation. **Steps 2 and 3 read that file.** A second run of the gather loop has broken this.
## Step 2: Identify Blocking Chains
Determine which specs are ready vs blocked (pure jq, works on any shell):
```bash
# Reuse the Step 1 gather — same literal path, NO re-fetch (one heavy loop total)
SPECS_FILE="${TMPDIR:-/tmp}/flow-deps-specs-<suffix>.json"
# Compute blocking status
jq -r '
# Build status lookup
(map({(.id): .status}) | add // {}) as $status |
# Check each non-done spec
.[] | select(.status != "done") |
.id as $id | .title as $title |
# Find deps that are not done
([.deps[] | select($status[.] != "done")] | join(", ")) as $blocked_by |
if ($blocked_by | length) == 0 then
"READY: \($id) - \($title)"
else
"BLOCKED: \($id) - \($title) (by: \($blocked_by))"
end
' "$SPECS_FILE"
```
### Done when
- Every non-`done` spec in `$SPECS_FILE` emitted exactly one `READY:` or `BLOCKED:` line, and each `BLOCKED:` line names the specific deps holding it.
- The jq ran against the cached file, not a fresh `flowctl show` sweep.
## Step 3: Compute Execution Phases
Group specs into parallel execution phases:
```bash
# Reuse the Step 1 gather — same literal path, NO re-fetch (one heavy loop total)
SPECS_FILE="${TMPDIR:-/tmp}/flow-deps-specs-<suffix>.json"
# Phase assignment algorithm (run in jq for reliability)
jq '
# Build status lookup
(map({(.id): .status}) | add // {}) as $status |
# Filter to non-done specs
[.[] | select(.status != "done")] as $open |
# Assign phases iteratively
reduce range(10) as $phase (
{assigned: [], result: [], open: $open};
.assigned as $assigned |
.open as $remaining |
# Find specs not yet assigned whose deps are all done or in earlier phases
([.open[] | select(
([.id] | inside($assigned) | not) and
((.deps // []) | all(. as $d | $status[$d] == "done" or ($assigned | index($d))))
)] | map(.id)) as $ready |
if ($ready | length) > 0 then
.result += [{phase: ($phase + 1), specs: [.open[] | select(.id | IN($ready[]))]}] |
.assigned += $ready
else . end
) |
# Emit the phases AND the residue: any open spec never assigned is UNRESOLVABLE — a
# dependency cycle (A→B→A), a dep on a missing/closed spec, or a chain deeper than 10.
# Dropping it silently is the one way /deps gives a WRONG answer (the graph it exists to
# expose hides the deadlock). Surface it, with the offending deps for diagnosis.
.assigned as $asg |
{ phases: .result,
deadlocked: [ $open[] | select(.id as $i | ($asg | index($i)) | not)
| { id, status,
unresolved_deps: [ (.deps // [])[] | select(. as $d | ($asg | index($d)) or ($status[$d] == "done") | not) ] } ] }
' "$SPECS_FILE"
```
### Done when
- The jq result carries both `.phases` and `.deadlocked`, and every open spec appears in exactly one of them.
- **The report is rendered from `.phases` and `.deadlocked`.** Phases narrated from a reading of the spec titles have broken this.
## Output Format
Present results as:
```markdown
## Spec Dependency Graph
### Status Overview
| Spec | Title | Status | Dependencies | Blocked By |
|------|-------|--------|--------------|------------|
| **fn-1-add-auth** | Add Authentication | **READY** | - | - |
| fn-2-add-oauth | Add OAuth Login | blocked | fn-1-add-auth | fn-1-add-auth |
| fn-3-user-profile | User Profile Page | blocked | fn-1-add-auth, fn-2-add-oauth | fn-2-add-oauth |
### Execution Phases
Render from the jq result's `.phases`:
| Phase | Specs | Can Start |
|-------|-------|-----------|
| **1** | fn-1-add-auth | **NOW** |
| 2 | fn-2-add-oauth | After Phase 1 |
| 3 | fn-3-user-profile | After Phase 2 |
### ⚠️ Deadlocked / Unresolvable
**This section renders exactly when `.deadlocked` is non-empty** — and when it does, it is the
most important part of the report. Each entry is an open spec that could not be placed in
any phase: a dependency **cycle**, a dep on a **missing/closed** spec, or a chain deeper
than 10. These are invisible to `ready`/`flow --auto` (they just never become ready) — this is the
one place the graph surfaces them.
| Spec | Status | Unresolved deps | Likely cause |
|------|--------|-----------------|--------------|
| fn-7-x | blocked | fn-9-y | fn-9-y not found / closed, or a cycle fn-7↔fn-9 |
For each, state the likely cause: if two deadlocked specs list each other → **cycle** (fix
with `flowctl spec rm-dep`); if an unresolved dep isn't among the open specs → **missing or
closed dependency**. **Every entry of `.deadlocked` reaches the report.** A report that lists phases while silently dropping an open spec has broken this.
### Critical Path
fn-1-add-auth → fn-2-add-oauth → fn-3-user-profile (3 phases)
```
**This skill is read-only inspection.** Edge changes are reported as commands for the
operator to run — `flowctl spec add-dep <spec> <dep>` / `rm-dep <spec> <dep>`. A run that
executes either command itself, or edits a spec file, has broken this.
## Quick One-Liner
For a fast dependency check:
```bash
$FLOWCTL specs --json | jq -r '.specs[] | select(.status != "done") | "\(.id): \(.title) [\(.status)]"'
```
## When to Use
- "What's the execution order for specs?"
- "What's blocking progress?"
- "Show me the dependency graph"
- "What's the critical path?"
- "Which specs can run in parallel?"
- "What should I work on next?"
© Gordon Mickel · MIT · gmickel/flow-next