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`

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

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

Designing a new feature → /flow-next:plan.
Executing a spec → /flow-next:work.
Refining a vague spec → /flow-next:interview.
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:plan <idea>     # design it
/flow-next:work <id>       # build it