Tasks & Inventory

The top-level flow-next skill handles conversational requests about the state of .flow/. It is the meta-skill behind phrases like:

“show me my tasks”
“list specs”
“what’s ready”
“add a task for X”
“show fn-1-add-oauth”
“task status”

It does not plan or work - those belong to /flow-next:plan and /flow-next:work. This skill is for inspection, quick edits, and bookkeeping.

What it can do

Intent	Underlying flowctl
List everything	`flowctl list --json`
List specs	`flowctl specs --json`
List tasks	`flowctl tasks --json` (with `--spec` or `--status` filters)
Show a spec or task	`flowctl show <id> --json`, `flowctl cat <id>`
What’s ready	`flowctl ready --spec <id> --json`
Add a task	`flowctl task create --spec <id> --title <...>`
Set task description and acceptance	`flowctl task set-spec <id> --description ... --acceptance ...`
Start a task	`flowctl start <id>`
Mark done	`flowctl done <id> --summary-file ... --evidence-json ...` (evidence JSON: `{"commits": ["<sha>"], "tests": ["<command>"], "prs": []}`)
Validate structure	`flowctl validate --spec <id>` / `--all`
Close a spec that won’t be built	`flowctl spec close <id> --retire superseded\|moot\|delivered-elsewhere [--by <spec-or-PR>]`

The skill picks the right flowctl invocation from the request and surfaces the result in conversational form.

Close a spec as won’t-do

Say “close fn-14, fn-22 replaced it” and the skill retires the spec instead of marking it built:

flowctl spec close fn-14-rate-limits --retire superseded --by fn-22-quota-service --json

Pick the reason that is true: superseded (another spec replaced it), delivered-elsewhere (it shipped under another spec or pull request) or moot (it is no longer needed, including a decision not to build it). Name each successor with --by. The spec’s never-run tasks read retired, not done, flowctl next stops offering them, and flowctl show prints retired: superseded by fn-22-quota-service. Completion review records not_required, so no gate holds the close open. Creating a task on the spec later reopens it. The CLI reference has the full contract.

Why it exists

flowctl is precise but verbose, and .flow/ is just files. The meta-skill bridges the two: ask in plain English, get a structured answer that you can act on or hand back to a slash command.

It is also the entry point for non-planning tasks like adjusting a spec’s evidence after the fact, or adding a small follow-up task that does not warrant a full /flow-next:plan run.

When NOT to use it

Building a new feature or change → /flow-next:flow <idea> (it picks the route and plans only on a signal).
Executing a spec → /flow-next:work.
Refining a vague spec → /flow-next:refine.
Choosing what to run next → /flow-next:flow --explain, or plain /flow-next:flow to run the route.
Synthesizing a conversation into a spec → /flow-next:capture.

If the request involves multi-step thinking, hand it to the dedicated skill. This one is for direct manipulation of .flow/.

Discovery

flowctl --help
flowctl <command> --help

flowctl is bundled with the plugin, not installed globally. The meta-skill resolves the bundled path automatically.

Worked example

what's ready to work on?

Ready tasks (fn-12-export-json-flag):
  fn-12-export-json-flag.1  Wire --json flag + JSON serializer
Ready tasks (fn-13-audit-log):
  fn-13-audit-log.1  Add audit-log table + writer
Blocked: fn-12-export-json-flag.2 (deps: .1)

Plain English in, flowctl ready out - the skill picks the right invocation and shows the structured answer.

Dynamic usage

Recipes that compose with the meta-skill in the cookbook:

Skip & lighten - quick task creation via conversation is the lightest possible ceremony for small follow-ups.
Integration tricks - the --json surfaces behind every answer script cleanly into your own tooling.

Next step

For anything beyond inspection and bookkeeping, hand off to the dedicated skill:

/flow-next:flow <idea>     # route and build it
/flow-next:work <id>       # build a spec you already have