facets-cloud/flow/skill

flow — task and session manager skill

1. What flow is

flow is a small CLI (assumed on $PATH) that the user uses to track personal work and bootstrap per-task agent sessions. Metadata (projects, tasks, workdirs, session IDs) lives in a single SQLite database at ~/.flow/flow.db. Free-form plan content lives on disk as markdown "briefs" at ~/.flow/projects/<slug>/brief.md and ~/.flow/tasks/<slug>/brief.md. Progress notes accumulate as dated markdown files under each entity's updates/ subdirectory. The user runs one long-lived Claude Code or Codex session per task in its own terminal tab, resumed via flow do <task>.

You are speaking inside one of those agent sessions (or the user's ambient "dispatch" session). Your job is to interpret the user's natural language requests and turn them into the exact flow commands and file edits they imply. You never edit flow.db directly. You never solve problems during task intake — you interview, then write what the user said.

Paths in this skill. Every ~/.flow/... path you see is the

default layout. The flow root is configurable via $FLOW_ROOT;

if it's set to something else, substitute that root in every path

reference. The authoritative paths are always whatever `flow show

task / flow show project print under brief:, updates:`,

kb:, etc. — read those, don't reconstruct paths from prose.

1a. When invoked explicitly with no intent

If this skill is invoked without a trigger phrase — for example the user typed /flow or asked you to load the flow skill but did not say what they want done — DO NOT auto-run any workflow. Do not silently call flow list tasks, do not enter §4.1 "start the day", do not propose opening a task, do not start an intake interview. The user just asked what this skill is for. Answer that question first; let them choose what happens next.

Behavior:

1. In 2–3 sentences, describe what you can do for the user with

flow under the hood — capture work as briefs, log progress notes, resume agent sessions across days, track what they're waiting on. Frame it as your capabilities, not commands. The user does not need to learn flow's CLI.

1. Use AskUserQuestion (header: "What now?") to offer the main

actions. Pick 3–4 options that fit the current state — for example:

• "Show me what's on my plate" — runs §4.1 start-the-day.
• "Add a new task" — runs §4.2 task intake.
• "Add a project" — runs §4.3 project intake.
• "Just exploring" — stop and wait.

1. Dispatch on the user's pick. If "Just exploring" or the user

skips the question, stop and let them lead.

This section ONLY governs the bare-invocation case. Trigger-phrase recipes in §4 ("what should I work on", "add a task", etc.) still fire on natural-language requests — when the user already expressed an intent, follow the matching recipe instead of re-asking via §1a.

2. The model

• Projects group related tasks: name, slug, work_dir, priority,

status (active/done), brief.md.

• Tasks are units of work: name, slug (via --slug), work_dir

(mandatory — project's, user-supplied, or auto-created ~/.flow/tasks/<slug>/workspace/ for floating tasks), priority, status (backlog/in-progress/done), optional project_slug, optional waiting_on note, brief.md. A task carries a harness session_id once flow do has bootstrapped it.

• Playbooks are reusable, runnable definitions (name, slug, work_dir,

optional project_slug, brief.md). Each invocation creates a playbook-run — a kind=playbook_run task with its own session, a snapshotted brief.md, and updates/. Editing the playbook brief doesn't affect past runs; runs are reproducible. See references/playbooks.md.

• Owners are durable, repo-scoped self-prompting controllers that own

an outcome via recurring fresh headless ticks (a charter.md + ledger + clock, self-pacing via flow owner next; --every is the fallback heartbeat floor). Status active/paused/retired. Managed tasks are tagged owner:<slug>; a human-decision task is also tagged question. See §4.17.

• Workdirs is a convenience registry of known local repo paths for

matching repo intent to disk — NOT the source of truth for a task's work_dir (tasks.work_dir is).

• Updates are dated markdown progress notes under

~/.flow/tasks/<slug>/updates/YYYY-MM-DD-<kebab>.md (and projects/), written by you via Write. Not in the DB; permanent — archiving never deletes them.

• Status is 3 values: backlog, in-progress, done (no blocked).

Waiting on someone → set waiting_on (§4.6). Set aside permanently → archive.

3. First-run detection & setup

The first flow command in a session doubles as an init probe; a brand-new user (missing DB) gets guided setup. The full recipe — the flow list probe, the "Set up flow?" AskUserQuestion, flow init, and the five-step first-run coaching — lives in references/setup.md. Read it when a flow command errors about a missing database, or when onboarding a fresh user.

4. Command reference

This is a terse cheat sheet. Use flow <command> --help for up-to-date flags.

Setup
  flow init                                 create ~/.flow/, init DB, install skill
  flow skill install [--force]              (re)install the skill file
  flow skill uninstall                      remove the skill
  flow skill update                         install --force after upgrading the binary
 
Create
  flow add project "<name>" --work-dir <path> [--slug <s>] [--priority h|m|l] [--mkdir]
  flow add task    "<name>" [--slug <s>] [--project <slug>] [--work-dir <path>] [--mkdir]
                           [--priority high|medium|low] [--due <date>] [--assignee <name>]
                           [--tag <t> ...]
  flow add playbook "<name>" --work-dir <path> [--slug <s>] [--project <slug>] [--mkdir]
  flow add owner    "<name>" --work-dir <path> --every <dur> [--slug <s>] [--project <slug>] [--mkdir]
 
Sessions
  flow do               <ref> [--harness claude|codex] [--fresh] [--dangerously-skip-permissions] [--force]
                              [--with "<instruction>" | --with-file <path>]
  flow do --here        <ref> [--force]   (bind THIS harness session to the task — no new tab)
  flow do --auto        <ref> [--with "<instruction>" | --with-file <path>]
                              (run headlessly in the background — no tab, no human; the
                               session does the work and self-completes via `flow done`.
                               Implies --dangerously-skip-permissions. Cannot combine with --here.)
  flow auto "<name>" --brief <file|-> [--slug <s>] [--priority p] [--work-dir <p>] [--mkdir] [--harness h]
                              (add task + write brief + do --auto in one shot; see §4.4a)
  flow done             <ref>
 
Playbook runs
  flow run playbook <slug> [--with "<instr>" | --with-file <path>]
                                    spawn a fresh run session (new task with kind=playbook_run)
  flow run playbook <slug> --here   bind THIS harness session to the new run (no new tab)
  flow run playbook <slug> --auto   run the playbook headlessly in the background (no tab, no human)
  flow list runs [<playbook-slug>]  list playbook runs (filter by playbook optional)
 
Owners (autonomous ownership — see §4.17)
  flow owner list                   all owners with status + next tick   (alias: flow list owners)
  flow owner show   <slug>          charter + what it owns (in-flight / playbook runs / questions) + next tick   (alias: flow show owner <slug>)
  flow owner start  <slug>          begin ticking — first tick now, then every <dur> (reactivates a paused OR retired owner)
  flow owner pause  <slug>          stop ticking, keep all state
  flow owner tick   <slug>          wake the owner NOW, interactively (a tab you drive); --auto = headless now
  flow owner next   <slug> --in <dur> | --at <when>   set the next tick time (how a tick self-paces)
  flow owner retire <slug> [--delete]   stop permanently (status=retired+archived); --delete removes row + dir
  (scheduled ticks run headlessly; `flow owner tick` is the on-demand / guided-first-run path)
 
Read
  flow show task    [<ref>]     (no arg → reverse-lookup via the active harness session id)
  flow show project [<ref>]     (no arg → project of the bound task)
  flow show playbook    [<ref>]
  flow transcript   [<ref>] [--compact]    (readable transcript from session jsonl)
  flow list tasks    [--status backlog|in-progress|done] [--project <slug>]
                     [--priority high|medium|low] [--since today|monday|7d|YYYY-MM-DD]
                     [--include-archived]
  flow list projects [--status active|done] [--include-archived]
  flow list playbooks   [--project <slug>] [--include-archived]
 
Edit / mutate
  flow edit           <ref>          opens brief.md in $EDITOR, bumps updated_at
  flow update task    <ref> [--work-dir <path>] [--mkdir]
                            [--status backlog|in-progress|done] [--priority high|medium|low]
                            [--assignee <name>] [--clear-assignee]
                            [--due-date <date>] [--clear-due]
                            [--waiting "<who or what>"] [--clear-waiting]
  flow update project <ref> [--priority high|medium|low]
  flow archive        <ref>
  flow unarchive      <ref>
  (flow edit, flow archive, flow unarchive also accept playbook refs)
 
Workdirs
  flow workdir list
  flow workdir add <path> [--name <nickname>]
  flow workdir remove <path>
  flow workdir scan [<root>] [--add]

All references (<ref>) resolve by exact slug match only. There is no fuzzy or substring matching. Use --slug to pick a short, memorable slug at creation time (e.g. --slug caas-exit). If omitted, a slug is auto-generated from the name (truncated to ~6 words).

4a. Interactive choices (use AskUserQuestion everywhere)

This section overrides any inline prose phrasing later in the skill. If a later section says "offer X", "ask Y", or "confirm Z", that always means "invoke AskUserQuestion with appropriate options" — never a prose question typed into the chat.

Every choice the user makes — always AskUserQuestion, never a prose question. Yes/no confirmations, pick-one-of-several, priority, slug suggestions, project attachment, mutation confirmations, "want me to do X?" — every single one runs through the tool so the user can click to select instead of typing. Common patterns:

Keep header under 12 chars. Put enough context in question so the choice is clear without scrolling back. If the user already answered in their message, don't re-ask — just use their answer.

Prose questions are deprecated. Don't write "Want me to do X?" or "Should I do Y?" or "(yes/no)" in chat — those force the user to type a free-text reply. The tool produces clickable options; always prefer the tool.

Mid-interview drift. Within an open-ended interview (intake, deferred-section prompt), the parent question may be free-form ("Why?", "Done when?") but follow-up clarifications often narrow into enumerable choices (architectures, install methods, yes/no). The moment a sub-question has 2–4 discrete options, switch to AskUserQuestion. Don't keep typing prose just because you started in prose. The "interview" framing governs the opening question; every narrowing inside it follows the same always-AskUserQuestion rule as the rest of the skill.

5. Core workflows