@manhquy/flow-skill 0.1.0-rc.1

package/skills/flow/harness/repo_map.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Reference-count repo-map: rank source files by how widely the symbols they DEFINE are
+referenced across the codebase (Aider's ranking idea, stdlib-only — no tree-sitter dependency,
+so it runs anywhere python 3 does). Best-effort: prints nothing and exits 0 when there is nothing
+rankable, so the caller (flow.sh assess) falls back to its flat scan.
+
+Usage: python repo_map.py <project_root> [top_n]
+"""
+import os
+import re
+import sys
+from collections import Counter
+
+SKIP_DIRS = {".git", "node_modules", ".flow", "plans", "dist", "build", "__pycache__",
+             ".venv", "venv", "vendor", ".idea", ".vscode", "target", "coverage", "cards",
+             "tests", "test", "spec", "__tests__", "e2e"}
+EXTS = {".py", ".js", ".ts", ".tsx", ".jsx", ".go", ".rs", ".sh", ".rb", ".java", ".kt"}
+MAX_BYTES = 512 * 1024  # skip very large files (binary-adjacent / generated) to bound memory + time
+# generic identifiers that carry no "this file is important" signal even when frequent
+STOPWORDS = {"main", "init", "name", "self", "this", "data", "value", "values", "item", "items",
+             "list", "index", "test", "tests", "args", "kwargs", "result", "results", "error",
+             "get", "set", "run", "make", "type", "config", "setup", "build", "parse", "func"}
+WORD = re.compile(r"[A-Za-z_]\w+")
+DEF_PATTERNS = [
+    re.compile(r"^\s*(?:async\s+)?def\s+([A-Za-z_]\w+)"),                    # python
+    re.compile(r"^\s*class\s+([A-Za-z_]\w+)"),                              # python/js/ts/java/kt
+    re.compile(r"^\s*(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_]\w+)"),  # js/ts
+    re.compile(r"^\s*(?:export\s+)?const\s+([A-Za-z_]\w+)\s*(?::[^=]+)?="),  # js/ts (incl. typed arrows: const x: T = )
+    re.compile(r"^\s*func\s+([A-Za-z_]\w+)"),                               # go
+    re.compile(r"^\s*(?:pub\s+)?fn\s+([A-Za-z_]\w+)"),                      # rust
+    re.compile(r"^\s*(?:pub\s+)?struct\s+([A-Za-z_]\w+)"),                  # rust
+    re.compile(r"^\s*([A-Za-z_]\w+)\s*\(\)\s*\{"),                          # shell  name() {
+]
+
+
+def iter_files(root):
+    # os.walk does NOT follow symlinks by default (no symlink-loop risk).
+    for dp, dirs, files in os.walk(root):
+        dirs[:] = [d for d in dirs if d not in SKIP_DIRS and not d.startswith(".")]
+        for fn in files:
+            if os.path.splitext(fn)[1] in EXTS:
+                yield os.path.join(dp, fn)
+
+
+def _defs_in(lines):
+    syms = set()
+    for ln in lines:
+        for pat in DEF_PATTERNS:
+            m = pat.match(ln)
+            if m:
+                name = m.group(1)
+                if len(name) >= 4 and name.lower() not in STOPWORDS:
+                    syms.add(name)
+    return syms
+
+
+def main(argv):
+    root = argv[1] if len(argv) > 1 else "."
+    top_n = int(argv[2]) if len(argv) > 2 else 10
+    files = list(iter_files(root))
+    if not files:
+        return 0
+    defs, def_files, freq = {}, Counter(), Counter()
+    for f in files:
+        try:
+            if os.path.getsize(f) > MAX_BYTES:
+                continue
+            with open(f, "r", encoding="utf-8", errors="ignore") as fh:
+                lines = fh.read().splitlines()
+        except OSError:
+            continue
+        syms = _defs_in(lines)
+        defs[f] = syms
+        for s in syms:
+            def_files[s] += 1
+        freq.update(WORD.findall("\n".join(lines)))   # tokenize ONCE per file (O(corpus) total)
+    ranked = []
+    for f in files:
+        # only symbols UNIQUELY defined in this file score it — a name defined in many files
+        # (utils, helper) is ambiguous and would give every definer the same inflated count.
+        uniq = [s for s in defs.get(f, ()) if def_files[s] == 1]
+        score = sum(max(0, freq.get(s, 0) - 1) for s in uniq)   # minus the definition itself
+        if score > 0:
+            top = sorted(uniq, key=lambda s: -freq.get(s, 0))[:3]
+            ranked.append((score, os.path.relpath(f, root).replace("\\", "/"), top))
+    ranked.sort(key=lambda x: (-x[0], x[1]))
+    for i, (score, rel, top) in enumerate(ranked[:top_n], 1):
+        print(f"{i}. {rel}  (score {score}; {', '.join(top)})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/skills/flow/harness/schema/001-init.sql

@@ -0,0 +1,129 @@
+-- Harness v0 schema — migration 001
+-- Durable layer for operational harness data.
+-- Policy docs (HARNESS.md, FEATURE_INTAKE.md, ARCHITECTURE.md) stay as
+-- human-readable references. This database stores the operational records
+-- that agents produce and query during work.
+
+PRAGMA journal_mode = WAL;
+PRAGMA foreign_keys = ON;
+
+----------------------------------------------------------------------
+-- Schema version
+----------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS schema_version (
+    version     INTEGER PRIMARY KEY,
+    applied_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+INSERT INTO schema_version (version) VALUES (1);
+
+----------------------------------------------------------------------
+-- Intake: classifying incoming work
+----------------------------------------------------------------------
+CREATE TABLE intake (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    created_at    TEXT    NOT NULL DEFAULT (datetime('now')),
+    input_type    TEXT    NOT NULL
+                         CHECK(input_type IN (
+                           'new_spec','spec_slice','change_request',
+                           'new_initiative','maintenance','harness_improvement'
+                         )),
+    summary       TEXT    NOT NULL,
+    risk_lane     TEXT    NOT NULL
+                         CHECK(risk_lane IN ('tiny','normal','high_risk')),
+    risk_flags    TEXT,          -- JSON array, e.g. ["auth","data_model"]
+    affected_docs TEXT,          -- JSON array of doc paths
+    story_id      TEXT,          -- links to story.id when one is created
+    notes         TEXT
+);
+
+----------------------------------------------------------------------
+-- Story: work packets and their validation status
+-- Replaces hand-edited TEST_MATRIX.md rows.
+----------------------------------------------------------------------
+CREATE TABLE story (
+    id               TEXT PRIMARY KEY,   -- e.g. US-001
+    title            TEXT NOT NULL,
+    created_at       TEXT NOT NULL DEFAULT (datetime('now')),
+    risk_lane        TEXT NOT NULL
+                     CHECK(risk_lane IN ('tiny','normal','high_risk')),
+    contract_doc     TEXT,               -- path to product doc
+    status           TEXT NOT NULL DEFAULT 'planned'
+                     CHECK(status IN (
+                       'planned','in_progress','implemented','changed','retired'
+                     )),
+    unit_proof       INTEGER NOT NULL DEFAULT 0,
+    integration_proof INTEGER NOT NULL DEFAULT 0,
+    e2e_proof        INTEGER NOT NULL DEFAULT 0,
+    platform_proof   INTEGER NOT NULL DEFAULT 0,
+    evidence         TEXT,
+    notes            TEXT
+);
+
+----------------------------------------------------------------------
+-- Decision: durable records with optional verification
+----------------------------------------------------------------------
+CREATE TABLE decision (
+    id                    TEXT PRIMARY KEY,  -- e.g. 0001
+    title                 TEXT NOT NULL,
+    created_at            TEXT NOT NULL DEFAULT (datetime('now')),
+    status                TEXT NOT NULL DEFAULT 'proposed'
+                          CHECK(status IN (
+                            'proposed','accepted','superseded','rejected'
+                          )),
+    doc_path              TEXT,              -- path to the markdown ADR
+    verify_command        TEXT,              -- optional check command
+    last_verified_at      TEXT,
+    last_verified_result  TEXT
+                          CHECK(last_verified_result IN ('pass','fail') OR
+                                last_verified_result IS NULL),
+    predicted_impact      TEXT,
+    actual_outcome        TEXT,
+    notes                 TEXT
+);
+
+----------------------------------------------------------------------
+-- Backlog: harness improvement proposals with evidence loop
+----------------------------------------------------------------------
+CREATE TABLE backlog (
+    id                    INTEGER PRIMARY KEY AUTOINCREMENT,
+    created_at            TEXT    NOT NULL DEFAULT (datetime('now')),
+    title                 TEXT    NOT NULL,
+    discovered_while      TEXT,
+    current_pain          TEXT,
+    suggested_improvement TEXT,
+    risk                  TEXT    CHECK(risk IN ('tiny','normal','high_risk')),
+    status                TEXT    NOT NULL DEFAULT 'proposed'
+                          CHECK(status IN (
+                            'proposed','accepted','implemented','rejected'
+                          )),
+    predicted_impact      TEXT,
+    actual_outcome        TEXT,
+    implemented_at        TEXT,
+    notes                 TEXT
+);
+
+----------------------------------------------------------------------
+-- Trace: agent task execution records (observability foundation)
+----------------------------------------------------------------------
+CREATE TABLE trace (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    created_at      TEXT    NOT NULL DEFAULT (datetime('now')),
+    task_summary    TEXT    NOT NULL,
+    intake_id       INTEGER REFERENCES intake(id),
+    story_id        TEXT    REFERENCES story(id),
+    agent           TEXT,
+    actions_taken   TEXT,       -- JSON array
+    files_read      TEXT,       -- JSON array
+    files_changed   TEXT,       -- JSON array
+    decisions_made  TEXT,       -- JSON array
+    errors          TEXT,       -- JSON array
+    outcome         TEXT
+                    CHECK(outcome IN (
+                      'completed','blocked','partial','failed'
+                    )),
+    duration_seconds INTEGER,
+    token_estimate   INTEGER,
+    harness_friction TEXT,
+    notes            TEXT
+);

package/skills/flow/harness/schema/002-story-verify.sql

@@ -0,0 +1,9 @@
+-- Harness v0 schema - migration 002
+-- Story-level mechanical verification.
+
+ALTER TABLE story ADD COLUMN verify_command TEXT;
+ALTER TABLE story ADD COLUMN last_verified_at TEXT;
+ALTER TABLE story ADD COLUMN last_verified_result TEXT
+    CHECK(last_verified_result IN ('pass','fail') OR last_verified_result IS NULL);
+
+INSERT INTO schema_version (version) VALUES (2);

package/skills/flow/harness/schema/003-tool-registry.sql

@@ -0,0 +1,15 @@
+-- Harness v0 schema - migration 003
+-- Machine-readable registry for user-provided project tools.
+
+CREATE TABLE tool (
+    name           TEXT PRIMARY KEY,
+    created_at     TEXT NOT NULL DEFAULT (datetime('now')),
+    provider       TEXT NOT NULL DEFAULT 'custom',
+    command        TEXT NOT NULL,
+    description    TEXT NOT NULL,
+    args           TEXT,
+    responsibility TEXT NOT NULL,
+    since          TEXT NOT NULL DEFAULT 'registered'
+);
+
+INSERT INTO schema_version (version) VALUES (3);

package/skills/flow/harness/schema/004-intervention.sql

@@ -0,0 +1,15 @@
+-- Harness v0 schema - migration 004
+-- Review, human, CI, or agent interventions separated from normal traces.
+
+CREATE TABLE intervention (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    created_at  TEXT NOT NULL DEFAULT (datetime('now')),
+    trace_id    INTEGER REFERENCES trace(id),
+    story_id    TEXT,
+    type        TEXT NOT NULL CHECK(type IN ('correction','override','escalation','approval')),
+    description TEXT NOT NULL,
+    source      TEXT NOT NULL CHECK(source IN ('human','reviewer','ci','agent')),
+    impact      TEXT
+);
+
+INSERT INTO schema_version (version) VALUES (4);

package/skills/flow/harness/schema/005-tool-extensions.sql

@@ -0,0 +1,20 @@
+-- Harness v0 schema - migration 005
+-- Inbound tool registry: kind-aware presence + capability binding.
+-- These columns turn the tool table from "declared intent" into
+-- "intent + last-scanned reality" without breaking existing rows.
+-- Adopted verbatim from repository-harness scripts/schema/005-tool-extensions.sql
+-- to keep migrations 001-005 a faithful port of the upstream harness schema.
+
+ALTER TABLE tool ADD COLUMN kind TEXT NOT NULL DEFAULT 'cli';
+ALTER TABLE tool ADD COLUMN capability TEXT;
+ALTER TABLE tool ADD COLUMN scan_target TEXT;
+ALTER TABLE tool ADD COLUMN status TEXT NOT NULL DEFAULT 'unknown';
+ALTER TABLE tool ADD COLUMN checked_at TEXT;
+
+-- Backfill kind for tools registered before kinds existed, inferring it from
+-- the agent-neutral command prefix convention so an upgrade does not mis-type
+-- (and then falsely flag as broken) MCP servers or skills that are not on PATH.
+UPDATE tool SET kind = 'mcp' WHERE command LIKE 'mcp:%';
+UPDATE tool SET kind = 'skill' WHERE command LIKE 'skill:%';
+
+INSERT INTO schema_version (version) VALUES (5);

package/skills/flow/harness/schema/009-accessed-count.sql

@@ -0,0 +1,11 @@
+-- Harness v0 schema - migration 009 (re-homed from 005 to free version 5 for the
+-- upstream tool-extensions migration; flow-specific, not in repository-harness).
+-- Usage signal: accessed_count tracks how often a durable row is surfaced by recall/query.
+-- Read-only reuse signal: incremented on read only, NEVER used to delete or prune a row
+-- (a rare-but-critical one-time lesson must survive a low access count). Surfaces what is reused.
+
+ALTER TABLE decision ADD COLUMN accessed_count INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE trace ADD COLUMN accessed_count INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE backlog ADD COLUMN accessed_count INTEGER NOT NULL DEFAULT 0;
+
+INSERT INTO schema_version (version) VALUES (9);

package/skills/flow/harness/schema/010-usage-event.sql

@@ -0,0 +1,42 @@
+-- Harness schema - migration 010 (re-homed from 006; flow-specific, not in repository-harness).
+-- Mechanical usage-log mirror. The append-only JSONL sinks (.flow/events.jsonl full,
+-- ~/.claude/flow/usage.jsonl compact) are the source of truth; this table is a derived,
+-- queryable rollup for `flow usage` stats. Idempotency rests on UNIQUE(src,line_no):
+-- re-rolling the same append-only line is ignored. rollup_cursor stores the last line
+-- number processed per source file (a skip-ahead optimization; correctness is the UNIQUE key).
+
+CREATE TABLE usage_event (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    src           TEXT    NOT NULL,        -- absolute path of the JSONL sink the row came from
+    line_no       INTEGER NOT NULL,        -- 1-based line number within that file
+    epoch_s       INTEGER,
+    session_id    TEXT,
+    cycle_id      TEXT,
+    project       TEXT,
+    command       TEXT,
+    args          TEXT,
+    exit_code     INTEGER,
+    gate_pass     INTEGER,                 -- 1 / 0 / NULL (non-gate command)
+    duration_s    INTEGER,
+    stage_from    TEXT,
+    stage_to      TEXT,
+    card          TEXT,
+    project_type  TEXT,
+    mode          TEXT,
+    flow_version  TEXT,
+    tier          TEXT,
+    host          TEXT,
+    read_only     INTEGER,
+    UNIQUE(src, line_no)
+);
+
+CREATE INDEX idx_usage_event_cycle ON usage_event(cycle_id);
+CREATE INDEX idx_usage_event_cmd   ON usage_event(command);
+
+CREATE TABLE rollup_cursor (
+    src         TEXT PRIMARY KEY,
+    last_line   INTEGER NOT NULL DEFAULT 0,
+    updated_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+INSERT INTO schema_version (version) VALUES (10);

package/skills/flow/harness/schema/011-usage-gate-reason.sql

@@ -0,0 +1,8 @@
+-- Harness schema - migration 011 (re-homed from 007; flow-specific, not in repository-harness).
+-- Record WHICH gate check failed (not just the gate_pass bool) so "stage X fails often" is
+-- diagnosable from the usage log. Additive column on the existing mirror; no new table.
+-- Old JSONL lines without the field roll up as NULL (back-compatible).
+
+ALTER TABLE usage_event ADD COLUMN gate_fail_reason TEXT;
+
+INSERT INTO schema_version (version) VALUES (11);

package/skills/flow/harness/schema/012-usage-ephemeral.sql

@@ -0,0 +1,10 @@
+-- Harness schema - migration 012 (re-homed from 008; flow-specific, not in repository-harness).
+-- Mark throwaway/test runs so device-wide analytics aren't dominated by them. A run is
+-- ephemeral when its project root is under the system temp dir or named like an mktemp dir.
+-- Additive column; old JSONL lines without the field roll up as NULL and are treated as
+-- non-ephemeral, except the read-time `project LIKE 'tmp.%'` fallback still excludes legacy
+-- temp runs from the default view (back-compatible, no log rewrite).
+
+ALTER TABLE usage_event ADD COLUMN ephemeral INTEGER;
+
+INSERT INTO schema_version (version) VALUES (12);

package/skills/flow/law/CLAUDE.md

@@ -0,0 +1,140 @@
+# Project rules — buildflow project
+
+This repo is a project run with the **buildflow** method. Planning artifacts live in
+`flow/`, build cards in `cards/`. The method: every stage/card has a GATE; no gate pass,
+no advance. Read `README.md` once for the method; THESE rules govern every session here.
+
+## /flow commands
+
+`/flow` (status) · `/flow next` (gate-check + unlock stage) · `/flow card` (new card) ·
+`/flow check C-NNN` (validate card) · `/flow mode teach|work` (who writes the plan) ·
+`/flow retro` (3 questions → RETRO.md / playbooks/ / FLOW-FEEDBACK.md) ·
+`/flow ready` (what's buildable now, parallel-safe groups) · `/flow auto` (autonomous
+build run — preflight via runner, then drive per SKILL.md AUTO PRINCIPLES: subagent per
+card, planner reviews + verifies, worktree isolation for parallel groups, operator-gated
+cards halt by design, state in card files + AUTO-LOG.md).
+Runner: `bash .claude/skills/flow/runner/flow.sh <cmd>`.
+
+Modes (`MODE` file at root; default `teach`): **teach** — the user writes every artifact,
+the AI only gatekeeps. **work** — the AI interviews the operator once, drafts stages 00-05
+itself, pauses only for scope sign-off, delivers the card set as one summary. Gates and
+done-rules are identical in both modes.
+
+## Build-session discipline (when implementing a card)
+
+1. ONE card per session. The card IS the session brief: build exactly its `## Scope`,
+   touch ONLY its `## Allowed files`. Need another file? Stop — amend the card first.
+   Default is serial, in card order. Parallel is allowed ONLY per the worktree protocol below.
+2. Two law files: the contract (`flow/05-contract.md`) for shapes, `DESIGN.md` for pixels.
+   Every UI card (mock + frontend) is built AND reviewed against DESIGN.md — tokens,
+   affordance ladder, object-first pattern, never-do list. Read it before any UI work.
+   The contract: never improvise a request/response shape.
+   If the contract is wrong, amend `flow/05-contract.md` FIRST, then code to it.
+   When the contract requires a field whose FEATURE belongs to a later card: honor the
+   SHAPE now (null/stub value, commented as such), deliver the VALUE in that feature's
+   card. Never omit the field — the UI card will consume the shape you ship.
+3. Run every `## Verify` step for real before claiming done. Paste actual output/URLs
+   into `## Evidence`. Only then set `status: done`, then run `/flow check C-NNN`.
+4. Done-evidence = world-state (deployed URL, curl output, DB row). "Tests pass" /
+   "code merged" are mid-pipeline, never done.
+5. Never check a gate box or write a planning artifact on the user's behalf.
+   Never set a card `done` without pasted evidence.
+6. Read any file flow.sh just created before first editing it.
+7. **Playbooks** (`playbooks/`): paid-for stack knowledge. Before building a card that
+   touches a stack with a playbook (check `playbooks/README.md` index), READ it and run
+   its smoke tests before committing to a design on that stack. After a card pays for a
+   non-obvious lesson, HARVEST it back into a playbook — the card review isn't done
+   until the lesson is filed. More stacks → more playbooks.
+
+## Standard card sequence
+
+1. **Scaffold + CI/CD** — repo, deploy pipeline, `/healthz` on a public URL. The scaffold
+   picks the spec-serving mechanism (FastAPI: free at `/docs` + `/openapi.json`; other
+   stacks: choose the generator in the ADR) — API docs are plumbing, not a later feature.
+2. **Vertical slice** — one contract endpoint + one ugly page calling it, deployed.
+   From this card on, `/docs` is LIVE on the deployed URL and shows the endpoint.
+3. **Backend cards** — one endpoint-group per card, built TO the contract.
+   **Swagger lands WITH the API**: every backend card's verify includes "the card's
+   endpoints appear in the live `/docs` with correct request/response schemas" — its
+   done-evidence includes the docs URL. Docs are never a catch-up card.
+4. **Contract-test card** — automated suite hitting EVERY contract endpoint with edge +
+   failure cases against the deployed API. The objective "feel safe" gate before UI.
+   If the framework serves OpenAPI (FastAPI: `/openapi.json`), the suite ALSO asserts
+   every `flow/05-contract.md` endpoint exists in the live spec with matching shapes —
+   planning contract and runtime swagger must never drift.
+5. **UI mock card** — static HTML, real copy, no logic/framework, rendered per `DESIGN.md`
+   (its tokens + patterns; the mock IS the design review). Done-evidence = the operator
+   viewed it in a browser and approved. Iterate here: mock retries cost seconds,
+   framework retries cost deploys.
+6. **Frontend cards** — implement the approved mock, consuming the contract, reviewed
+   against `DESIGN.md`.
+7. **E2E card** — automated browser test over the DEPLOYED app covering the PRD's user
+   actions; its run doubles as verify-live.
+
+## PR & merge protocol
+
+Once the scaffold card lands, **main = deployable** (auto-deploy watches it). From then on:
+
+1. **Branch per card**: `card/C-NNN`, serial or parallel alike. No direct commits to main.
+2. **Commits**: plain ASCII messages (smart quotes / arrows can break CI+deploy hooks),
+   prefixed with the card id (`C-003: resident reply endpoint`), one logical change each.
+3. **PR per card** when the repo has a remote: title = the card's title; body = the card's
+   scope + the verify outputs (paste real runs). The card review — diff vs scope, vs
+   allowed-files, vs contract shapes, vs DESIGN.md for UI — happens ON the PR diff,
+   BEFORE merge. A card with failing verify steps does not get a PR.
+4. **Merge rules**:
+   - Merge in card-number order (deps guarantee order makes sense).
+   - After `gh pr create`, pushing more commits is a trap on squash-merge — trailing
+     commits can silently drop. If you must push post-create, re-check the PR's commit
+     list before merging, and verify the merged SHA on main contains every change.
+   - Delete the branch (and worktree) after merge — never with unmerged work.
+5. **Merge ≠ shipped.** After merge: deploy runs → verify the change on the LIVE URL
+   (deploy-success is not proof the surface changed). Only then does the card's
+   `## Evidence` get its world-state proof and `status: done`.
+6. **Auto runs**: the planner opens the PR, reviews the diff, merges green cards without
+   asking (Tier-A), and logs PR URL + merged SHA per card in AUTO-LOG.md. A red review
+   goes back to a fresh subagent (two-strikes rule applies).
+7. **No remote?** Local-only projects keep the same shape minus the PR: branch per card,
+   review the diff before merging to main, same live-verify rule.
+
+## Debt (deliberate gate-skips)
+
+Reordering past the standard sequence or skipping a gate is a legitimate OPERATOR call
+(demo-first, riskiest-first). But a skipped gate is a loan, and loans get written down:
+
+1. Every deliberate skip opens a line in `DEBT.md` (create it on first use):
+   `- [ ] DEBT: <what was skipped> — <the exposure, concretely> — close before: <named
+   condition, e.g. "any real user touches this"> — opened <date> (cards: C-NNN…)`
+2. **Security-class skips** (auth, public exposure of admin surfaces, tenancy, payments)
+   are NEVER silent and never planner-decided: the operator explicitly accepts the
+   exposure, in writing, in the DEBT line. In auto runs this is a Tier-C halt.
+3. A debt's close condition is checked at every retro and before anything is given to a
+   real user. Closing a project run with open security debt requires an explicit
+   operator acknowledgment — "temporary" is one forgotten step from production.
+4. Cards blocked by a debt (built but can't honestly reach done-evidence) stay
+   `todo` with PARTIAL evidence naming the debt — never half-done, never rounded up.
+
+## Parallel builds (worktree protocol)
+
+Cards declare `deps:` (card ids, or "none"). `bash .claude/skills/flow/runner/flow.sh ready`
+computes which todo cards have deps met AND no allowed-files overlap — only those may run
+in parallel. The runner advises; the OPERATOR dispatches. Rules:
+
+1. One card = one worktree = one session:
+   `git worktree add ../<project>-C-NNN -b card/C-NNN`
+2. A session in a worktree obeys its card's allowed-files exactly (overlap was checked
+   against the card text — drifting outside it breaks the parallel-safety guarantee).
+3. Merge back in card-number order, one at a time: `/flow check C-NNN` passes →
+   merge to main → run the merged app once (deps-done means INTERFACE done, not proven
+   integration) → only then merge the next. Conflicts on merge = the overlap check was
+   gamed; stop and re-plan.
+4. Remove the worktree after merge: `git worktree remove ../<project>-C-NNN`.
+5. Cards whose verify needs the deployed app (contract-tests, e2e) are SERIAL by nature —
+   don't parallelize them.
+
+## Forbidden
+
+- Building two cards in the SAME worktree/session, or in parallel without `flow.sh ready`
+  marking them safe (planning all cards up front is fine).
+- Editing `_templates/` or `flow.sh` during a project run.
+- Frontend code before the UI mock card is approved.

package/skills/flow/law/DESIGN.md

@@ -0,0 +1,141 @@
+# Design law — buildflow projects
+
+This file is LAW for every UI card in this project — the UI mock card and every
+frontend card MUST be built and reviewed against it. If a change conflicts with a rule
+here, the rule wins (or the rule is changed deliberately, in this file, with a dated note).
+
+Two layers, treat them differently:
+- **Structure is law**: the affordance ladder, object-first pattern, forms rules, and the
+  never-do list apply to any product. Don't relitigate these per project.
+- **Tokens are taste**: the colors, fonts, and gradients below are one good default.
+  A project MAY replace them — deliberately, in this file, all at once, with a dated
+  note — never ad-hoc per component.
+
+## North Star
+
+**Simple stupid UI for non-technical users; full power kept available — but never in the way.**
+
+Users think in *their* objects ("my workshop", "my ticket", "my booking") — never in
+engine concepts. Engine words (workflow, trigger, action, job, queue, webhook, agent,
+prompt…) NEVER appear in user-facing copy. Define this project's vocabulary in the
+table below and use it everywhere.
+
+### Project vocabulary (fill per project — strings, never code paths)
+
+| Engine concept | This project's user word |
+|---|---|
+| _(e.g. async agent run)_ | _(e.g. "đang phân loại…")_ |
+
+## Five rules that override everything
+
+1. **Object-first, not feature-first.** The home page of a thing IS the thing. Tabs are
+   lenses on the same object — the user never navigates "out" to reach something related.
+2. **WYSIWYG, edited in place.** The daily 80% of edits happen inline on the object's own
+   page (see the affordance ladder). A separate Edit page exists only for the structural 20%.
+3. **Defaults beat configuration.** Creatable in ≤6 visible fields; everything else behind
+   one "More options" disclosure. If a default serves 80%, ship it and demote the toggle.
+4. **Plain language beats power syntax.** "4 days after it ends" — never cron. A field-picker
+   chip — never `{{ raw.templates }}`. No JSON in any simple surface.
+5. **Power behind a door.** If a power surface exists, it's a `Simple | Pro` toggle that
+   never loses data, plus a visible "switch to simple" path back. 95% never flip it.
+
+## Edit-affordance ladder (inline ↔ popup is a spectrum, not a switch)
+
+Choose by the field's SEMANTIC SHAPE — always the lightest rung the shape allows.
+Decision rule: count the inputs the user must touch to finish the edit.
+
+| Rung | Field shape | Interaction |
+|---|---|---|
+| 1. Inline text | one free-text value | click → input in place → save on blur/Enter (optimistic) |
+| 2. Inline control | one value, known set/format | click → the right native control in place (date picker, stepper, select) |
+| 3. Popover composite | ONE displayed line composed of 2–4 sub-choices | click → popover anchored to the field, type-switch + matching input → "Done" writes one line |
+| 4. Modal | a multi-field object, or a collection | "+ Add" / "Edit" → centered dialog with all fields |
+
+- Popover edits **one display value**, dims nothing. Modal edits **an object or list**, dims the page.
+  Finishing produces one chip → popover. A new row in a list → modal. Never swap them.
+- Inline-editable fields: text by default; hover reveals dotted underline + a 12px pencil;
+  click becomes the right affordance.
+- **Empty state rides the same ladder**: a missing value renders as a dashed `+ Add {label}`
+  that opens its own rung. No field is ever a dead-end.
+
+## Object page pattern (the Luma pattern)
+
+Every object-detail page:
+- **Pulse strip** — at-a-glance metrics inline (calm, no stat-tile cards, no shadows).
+- **Up to 3 hero action cards** — the top things a user does on this object. Big targets,
+  gradient-tinted, one click. NOT a kebab menu.
+- **Tabs as lenses** — all on the same object. Active tab: 2px bottom border `var(--fg-base)`.
+- **Modal-first sub-actions** — small focused modals, one CTA. No multi-screen flows.
+- **The overview shows less, not more.** Heavy lifting goes to specialized tabs.
+
+## Editorial Minimal tokens (locked)
+
+| Token | Value | Use |
+|---|---|---|
+| `--bg-base` | `#FFFFFF` | page bg, cards |
+| `--bg-subtle` | `#FAFAFA` | sidebar, savebar, secondary surfaces |
+| `--bg-muted` | `#F4F4F5` | hover, muted chips |
+| `--fg-base` | `#09090B` | primary text, primary buttons |
+| `--fg-muted` | `#52525B` | body, descriptions |
+| `--fg-subtle` | `#71717A` | helper text, timestamps |
+| `--border` | `#E4E4E7` | all 1px borders |
+| `--accent` | `#4F46E5` | focus rings, accent links, validate-ok |
+
+**Typography**: `Inter` body/labels/buttons · `Fraunces` h1, card titles, prominent stat
+values ONLY · `JetBrains Mono` identifiers, dates, counts, machine-shaped content ONLY.
+Don't sprinkle serif on body text or mono on prose.
+
+**Borders**: 1px `var(--border)`. No drop shadows except focus rings, active sidebar item,
+and hero-card hover lift. One purposeful elevation, never shadow noise.
+
+## Soft gradients (highlight, not decorate)
+
+Hero surfaces ONLY (hero action cards, gallery/list covers, pulse backdrop). NEVER on
+tables, form inputs, sidebars, page backgrounds, or body rows.
+
+```css
+--grad-peach:    linear-gradient(135deg, #FFF4EC 0%, #FEE7D6 100%);  /* action / first in a series */
+--grad-mint:     linear-gradient(135deg, #ECFDF3 0%, #D1F4DD 100%);  /* money / success / all-green */
+--grad-sky:      linear-gradient(135deg, #EEF4FF 0%, #DCE7FF 100%);  /* info / context banners */
+--grad-lavender: linear-gradient(135deg, #F3EEFF 0%, #E2D6FB 100%);  /* primary surface / pulse */
+--grad-rose:     linear-gradient(135deg, #FFF1F4 0%, #FDDDE3 100%);  /* social / sharing / accent */
+--grad-pulse:    linear-gradient(90deg, #FAFAFA 0%, #F3EEFF 50%, #FAFAFA 100%); /* subtle strips */
+```
+
+Hover on gradient cards: lift `translateY(-1px)` + `box-shadow: 0 8px 24px rgba(9,9,11,.06)`;
+no hard accent border.
+
+## Forms
+
+- Max 6 visible fields on any create/edit page; more → disclosure.
+- One column, max-width 640px for focused forms. No multi-step wizards for editing.
+- Sticky savebar: white, 1px top border, optional 4px gradient accent strip.
+- Labels 12px / 500 / `var(--fg-muted)`. Inputs 38px tall, 1px border, accent focus ring.
+
+## Iconography
+
+Stroke line icons (Heroicons/Lucide style), stroke-width 1.6–2, no fill.
+**No emojis. Anywhere. Ever.** Use SVGs.
+
+## VN conventions (when the project is Vietnamese-facing)
+
+- Vietnamese copy throughout the user surface — written natively, not translated.
+- Prices: `₫750,000` — symbol leading, comma groups. Never "VND 750000.00".
+- VietQR scan-to-pay as the default payment presentation; cards demoted to "Thẻ quốc tế".
+- Zalo as a first-class support-channel option, not only email.
+
+## What to never do
+
+- Never leak engine words into user-facing copy (see vocabulary table).
+- Never show raw `{{ }}` templates or JSON outside a power-user surface.
+- Never use multi-step wizards for editing.
+- Never gradient form inputs, body backgrounds, or table rows.
+- Never stack shadows. Never add emojis. Never write design comments in HTML.
+
+## How this binds the cards
+
+- The **UI mock card** renders these tokens/patterns in static HTML — the mock IS the
+  design review; the operator approves against this file.
+- Every **frontend card**'s review checks the diff against this file the same way it
+  checks shapes against `flow/05-contract.md`. DESIGN.md is to pixels what the contract
+  is to shapes.

package/skills/flow/law/RETRO.md

@@ -0,0 +1,13 @@
+# Retro
+
+After all cards are done, append ONE line per project run:
+*Which gate did I skip or rush, and what did it cost?*
+
+**Optional aid — the `retro` SKILL (opt-in).** Before writing the line, you may offer the `retro`
+skill (git-history-driven: commit/velocity/code-health numbers) so the retro is backed by real
+figures, not memory. It INFORMS the operator's line — **the operator still writes the line; the
+skill never authors it** (the teach-mode rule holds). Distinct from the `journal-writer` agent
+(narrative) — see `claudekit-skills.md`. After it runs at this gate, record the lazy durable
+metric via `flow.sh harness intervention add`.
+
+---