# Tasks & Inventory

Source: https://flow-next.dev/skills/flow-next/

Conversational access to specs and tasks in .flow/ - the meta-skill behind 'show me my tasks'.

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

```bash
flowctl --help
flowctl <command> --help
```

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

## Worked example

```plaintext
what's ready to work on?
```

```text
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.

* Use it for the bookkeeping that does not deserve a full skill run: fixing a task’s evidence after the fact, adding a small follow-up task, checking status mid-review.
* Anything multi-step belongs to the dedicated skill - the meta-skill deliberately refuses to plan or implement.
* The same data is always available raw: `flowctl list`, `show <id> --json`, `cat <id>` - the skill is a convenience, not a gatekeeper.

## Dynamic usage

Recipes that compose with the meta-skill in the [cookbook](https://flow-next.dev/guides/cookbook/):

* [Skip & lighten](https://flow-next.dev/guides/cookbook/#skip--lighten) - quick task creation via conversation is the lightest possible ceremony for small follow-ups.
* [Integration tricks](https://flow-next.dev/guides/cookbook/#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:

```bash
/flow-next:plan <idea>     # design it
/flow-next:work <id>       # build it
```