flow-first

Flow-First Protocol

Input

The block's task description plus 2-3 anchors (file / DB table / route / service / UI component) from the user.

Output

A 4×3 table (Landscape / Problem / Solution / Result across UI / DB / Integrations) saved as flow-first-{N}.{R}.md.

Hands off to

library-first (auto-invoked after user approval).

---

Introduction

An understanding-alignment protocol before moving to library-first.

Why it's needed: library-first assumes the agent already understands what is being done and at which levels. Without that understanding, library-first is built on guesses — wrong layer searched, wrong LOC estimate, wrong "ready-made" solution. flow-first closes that gap in 5-10 minutes before planning begins.

Key principle: the agent reads only what the user specified — 2-3 anchors (file, table, route, service). No project-wide scanning.

---

Step 0 — Check task context

Check: are {log_dir} and {slug} known in the current session?

If yes — continue. If no — list latest task folders under {tasks_root}/log/, ask which is current, set {slug} and {log_dir}. Cannot skip — without {log_dir} the artifact won't be saved.

---

Step 0.5 — Incoming-artifact calibration

flow-first can be invoked inside a per-block cycle or manually. Read earlier artifacts if present:

ls "{log_dir}"/idea-first-*.md 2>/dev/null | head -1
ls "{log_dir}"/habit-first-*.md 2>/dev/null | head -1
ls "{log_dir}"/research-doc.md 2>/dev/null | head -1

• idea-first-*.md → extract task type (product/feature/fix) and scope
• habit-first-*.md → behavioural context for new-product tasks
• research-doc.md → ready comparison "as is vs should be"

If none found — continue. flow-first works without them.

Step 0.5.0 — UPDATE block status pending → open

Move current block from pending to open:

sqlite3 {routing_db} \
  "UPDATE task_blocks SET status='open'
   WHERE task_id='{slug}' AND block_num={N} AND status='pending';"