git:20260815.bfe5cd9 to git:20260828.53a2584

1 added, 1 removed. Audit A to A.

---

name: flow-next

description: "Manage .flow/ tasks and specs. Triggers: 'show me my tasks', 'list specs', 'what tasks are there', 'add a task', 'create task', 'what's ready', 'task status', 'show fn-1-add-oauth'. NOT for /flow-next:plan or /flow-next:work."

---

# Flow-Next Task Management

Quick task operations in `.flow/`. For planning features use `/flow-next:plan`, for executing use `/flow-next:work`.

## Preamble

**CRITICAL: flowctl is BUNDLED — NOT installed globally.** `which flowctl` will fail (expected). 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"

```

**Discover all commands/options:**

```bash

$FLOWCTL --help

$FLOWCTL <command> --help # e.g., $FLOWCTL task --help

```

## Quick Reference

```bash

# Check if .flow exists

$FLOWCTL detect --json

# Initialize (if needed)

$FLOWCTL init --json

# List everything (specs + tasks grouped)

$FLOWCTL list --json

# List all specs

$FLOWCTL specs --json

# List all tasks (or filter by spec/status)

$FLOWCTL tasks --json

$FLOWCTL tasks --spec fn-1-add-oauth --json

$FLOWCTL tasks --status todo --json

# View spec with all tasks

$FLOWCTL show fn-1-add-oauth --json

$FLOWCTL cat fn-1-add-oauth # Spec markdown

# View single task

$FLOWCTL show fn-1-add-oauth.2 --json

$FLOWCTL cat fn-1-add-oauth.2 # Task spec

# What's ready to work on?

$FLOWCTL ready --spec fn-1-add-oauth --json

# Create task under existing spec

$FLOWCTL task create --spec fn-1-add-oauth --title "Fix bug X" --json

# Set task description and acceptance (combined, fewer writes; unique per-task temp paths)

$FLOWCTL task set-spec fn-1-add-oauth.2 --description "${TMPDIR:-/tmp}/flow-desc-fn-1-add-oauth.2.md" --acceptance "${TMPDIR:-/tmp}/flow-accept-fn-1-add-oauth.2.md" --json

# Or use stdin with heredoc (no temp file):

$FLOWCTL task set-description fn-1-add-oauth.2 --file - --json <<'EOF'

Description here

EOF

# Start working on task

$FLOWCTL start fn-1-add-oauth.2 --json

# Mark task done

echo "What was done" > /tmp/summary.md

echo '{"commits":["abc123"],"tests":["npm test"],"prs":[]}' > /tmp/evidence.json

$FLOWCTL done fn-1-add-oauth.2 --summary-file /tmp/summary.md --evidence-json /tmp/evidence.json --json

# Validate structure

$FLOWCTL validate --spec fn-1-add-oauth --json

$FLOWCTL validate --all --json

```

## Common Patterns

### "Add a task for X"

1. Find relevant spec:

```bash

# List all specs

$FLOWCTL specs --json

# Or show a specific spec to check its scope

$FLOWCTL show fn-1 --json

```

2. Create task:

```bash

$FLOWCTL task create --spec fn-N --title "Short title" --json

```

3. Add description + acceptance (combined):

```bash

# Unique per-task temp paths — written + consumed in this one block

cat > "${TMPDIR:-/tmp}/flow-desc-fn-N.M.md" << 'EOF'

**Bug/Feature:** Brief description

**Details:**

- Point 1

- Point 2

EOF

cat > "${TMPDIR:-/tmp}/flow-accept-fn-N.M.md" << 'EOF'

- [ ] Criterion 1

- [ ] Criterion 2

EOF

$FLOWCTL task set-spec fn-N.M --description "${TMPDIR:-/tmp}/flow-desc-fn-N.M.md" --acceptance "${TMPDIR:-/tmp}/flow-accept-fn-N.M.md" --json

```

### "What tasks are there?"

```bash

# All specs

$FLOWCTL specs --json

# All tasks

$FLOWCTL tasks --json

# Tasks for specific spec

$FLOWCTL tasks --spec fn-1-add-oauth --json

# Ready tasks for a spec

$FLOWCTL ready --spec fn-1-add-oauth --json

```

### "Show me task X"

```bash

$FLOWCTL show fn-1-add-oauth.2 --json # Metadata

$FLOWCTL cat fn-1-add-oauth.2 # Full spec

```

(Legacy `fn-1.2` / `fn-1-xxx.2` still works.)

### Create new spec (rare - usually via /flow-next:plan)

```bash

$FLOWCTL spec create --title "Spec title" --json

# Returns: {"success": true, "id": "fn-N-spec-title", ...}

```

### Close a spec as won't-do

```bash

$FLOWCTL spec close fn-1-add-oauth --json

```

- A spec closed **because we decided not to build it** also gets a file in `.flow/memory/declined/<concept-slug>.md`, written directly (agent prose, no flowctl verb): title, the decision in one line, short reasoning, and a `## Prior requests` list opened with today's date and where the request came from. The file already exists → append the dated line under `## Prior requests` and leave the decision as written. Without it the concept comes back next quarter with nothing to point at, and the next planner proposes it fresh.

+ A spec closed **because we decided not to build it** also gets a file in `.flow/memory/declined/<concept-slug>.md`, written directly (agent prose, no flowctl verb): title, the decision in one line, short reasoning, and a `## Prior requests` list opened with today's date and where the request came from. The file already exists → append the dated line under `## Prior requests` and leave the decision as written. The entry body follows the artifact prose contract in [docs/prose.md](../../docs/prose.md); proceed without it when the doc is absent. Without it the concept comes back next quarter with nothing to point at, and the next planner proposes it fresh.

**Only a policy refusal earns a file.** A spec closed as superseded, merged into another spec, already implemented, or obsolete is not a decline — filing it there teaches future planners that shipped or in-flight work is rejected scope. Reopening a declined concept is the user's call alone.

## ID Format

- Spec: `fn-N-slug` where slug is derived from title (e.g., `fn-1-add-oauth`, `fn-2-fix-login-bug`)

- Task: `fn-N-slug.M` (e.g., `fn-1-add-oauth.1`, `fn-2-fix-login-bug.2`)

Legacy formats `fn-N` and `fn-N-xxx` (random 3-char suffix) are still supported.

## Notes

- Run `$FLOWCTL --help` to discover all commands and options

- **Every write goes through a flowctl subcommand.** A session that edits `.flow/` JSON or task markdown by hand has broken this.

- **Every read comes from `.flow/` state**, via `--json` (`detect`, `list`, `specs`, `tasks`, `show`, `ready`) or `cat` for markdown. An answer assembled from files skimmed by hand has broken this.

- **A task marked complete is closed with `flowctl done` carrying both `--summary-file` and `--evidence-json`.** A bare status flip has broken this.

- **Requests that need real planning or execution are handed off**, to `/flow-next:plan` and `/flow-next:work`. Improvising them here has broken this.