flow-next-deps
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'.
gmickel · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add gmickel/flow-next --skill flow-next-depsAbout this skill
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:
FLOWCTL="${CODEX_HOME:-$HOME/.codex}/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
$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 prompt turns, 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):
# 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_FILEexists at the composed literal path and parses as a JSON array with one object per spec returned byflowctl specs --json.- The per-spec
flowctl showloop 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):
# 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-
donespec in$SPECS_FILEemitted exactly oneREADY:orBLOCKED:line, and eachBLOCKED:line names the specific deps holding it. - The jq ran against the cached file, not a fresh
flowctl showsweep.
Step 3: Compute Execution Phases
Group specs into parallel execution phases:
# 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
.phasesand.deadlocked, and every open spec appears in exactly one of them. - The report is rendered from
.phasesand.deadlocked. Phases narrated from a reading of the spec titles have broken this.
Output Format
Present results as:
## 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 sp
Read the complete source ↗