@manhquy/flow-skill 0.1.0-rc.1

package/skills/flow/references/gate-rules.md

@@ -0,0 +1,171 @@
+# Gate rules — the semantic layer
+
+The runner (`flow.sh`) checks the mechanical gate: no `[FILL]`, no unchecked `- [ ]`, valid
+card status, non-empty evidence. **This file is what YOU check after the script passes.**
+The script cannot judge truth or quality; you can. For each stage, after a mechanical PASS,
+run the challenge below. If it fails, tell the operator: *"mechanically passed, but
+qualitatively weak: <reason>"* and let them decide — never silently advance a hollow
+artifact, never silently block a sound one.
+
+> Rule of behavior: in `teach` mode you do NOT edit the artifact or tick boxes. You report.
+> In `work` mode you authored it, so you self-challenge before presenting.
+
+> Authoring note (when editing these challenges): **match the form to the failure.** A challenge
+> that fights a *discipline drift* — the agent rationalizing a hollow artifact through (grade
+> laundering, fabricated quotes, "merge ≈ shipped") — is rightly a prohibition + the specific
+> rationalization it counters. A challenge that fixes a *wrong-shaped artifact* (a missing field, a
+> drifted name) is better written as a positive recipe — "every interface has both shapes, names
+> that won't drift" — than as a ban; a bare prohibition on a shaping problem can produce *more* of
+> the bad shape, not less, and a hedging "unless it matters" clause turns a crisp recipe noisy. Pick
+> the form deliberately; don't reflexively reach for another "do NOT".
+
+## Stage 00 — Idea
+Mechanical: pitch present, one real person named, no FILL.
+**Challenge:** Is the pitch really 3 sentences (who / pain / what)? Is the named person a
+*real, specific* person or group ("my uncle's 20-unit building"), not "people who..." or
+"users"? Is the pain concrete, not a category?
+
+## Stage 01 — Research
+Mechanical: 7 boxes checked, no FILL.
+**Apply the lens by project type (`/flow project-type`, default web):**
+- **web / market product** → the strict version below. Reject the soft "non-web" framing for a
+  product that has a real market: a real product DOES have online complaints + a GTM channel,
+  and dodging them is the failure this gate exists to catch.
+- **cli / library / skill / internal tool** → items 2+4 use first-party friction + who-benefits.
+  Demand it be *concrete and real* (a named observed pain, named beneficiaries) — not vague.
+  "No market channel" is expected here and is NOT a kill signal.
+**Challenge (highest fabrication risk):**
+- Were 3 competitors *actually opened*? Each note should read like someone used the tool. (all types)
+- web: are the 3 complaints *real quotes with working source links*? · non-web: is the
+  first-party friction *concrete and observed* (who hit it, when), not a guess?
+- Are competitor/status-quo costs *real* (web: prices+who-pays · non-web: time/manual-work spent today)?
+- web: is the first-10-users channel a *specific place* (reject "social media"/"online") ·
+  non-web: are the *named beneficiaries* + how-they-learn real?
+- Does the switch reason name what makes the *named* users move off today's workaround?
+
+## Stage 02 — Scope (the decision stage)
+Mechanical: every feature has Impact (H/M/L) + Grade (A/B/C), no L-above-A in v1, cut list,
+GO/KILL, no FILL.
+**Challenge — watch for GRADE LAUNDERING:**
+- Is any expensive feature quietly graded B when it's really C? (realtime, payments from
+  scratch, custom auth, autonomous agentic pipeline, heavy concurrency = C). Call C a C.
+- For every C in scope, is it justified as one of: (1) C IS the product -> it goes FIRST;
+  (2) re-architected C->B (e.g. multi-step agent -> single structured call; auto-send ->
+  human-approves-draft; custom -> managed service); (3) irreducible -> KILL/re-budget?
+- Classic failure: v1 full of A-grade L-impact features (cheap to build, worthless to sell).
+- If the product itself is a C, is it FIRST in build order with sibling Cs on the cut list?
+
+## Stage 03 — PRD
+Mechanical: filled from stage 02, numeric success metric, pain&gain table, no FILL.
+**Challenge:**
+- Is the success metric a real NUMBER ("first response < 2h"), not "save time" / "better UX"?
+- The pain&gain table is the spine: does *every pain* cite evidence (a stage-01 quote or
+  named observation) AND name the v1 feature that kills it? Does *every v1 feature* kill at
+  least one pain? Orphans on either side = scope drift.
+- Could a stranger build v1 from this without asking the operator anything?
+
+## Stage 04 — ADR
+Mechanical: each decision has why + rejected, NOT-doing list, covers storage/auth/deploy.
+**Challenge:** Does each decision name a *real* rejected alternative (not a strawman)? Are
+data storage, auth approach, and deploy target all actually decided (not "TBD")? Is the
+NOT-doing list honest about what's deferred?
+- **Optional `ck-predict` (when present, non-trivial decision).** Before locking a risky
+  decision, offer a 5-persona debate (`ck-predict`) — it surfaces arch/security/perf/UX defects
+  when reversal is cheapest. Output INFORMS this challenge; it never passes the gate. Skip on a
+  trivial ADR (opt-in-with-prompt — see `claudekit-skills.md`).
+
+## Stage 05 — Contract (the seam)
+Mechanical: every PRD feature -> >=1 interface, every interface has input+output shapes,
+access/effects column filled, no FILL.
+**The "interface" is the project type's seam** (`/flow project-type`): web=endpoint,
+cli=command+flags+output/exit, library=public function+args+return, skill=command/file.
+**Challenge — this is where producer/consumer drift is born (every type):**
+- Does every PRD feature map to at least one interface, and vice versa?
+- Does every interface have BOTH input and output shapes, with field/flag names that will not
+  drift (the #1 AI-build failure: backend ships `player_email`, UI assumed `email`, both green;
+  the cli equivalent: `--out` vs `--output`)?
+- Is the access/effects column real for every interface (web: public/token/admin · non-web:
+  writes/side-effects or "none")? Do NOT let a web product blank the access column.
+- One-way rule: this file is planning source of truth. For web the served spec
+  (`/openapi.json`) is the runtime artifact of the SAME contract (amend file -> code -> spec).
+  For non-web there is no served spec — the no-drift check is the per-type done-evidence.
+- **Self-consistency pass (the contract is ground truth every downstream card trusts).** Before
+  passing this gate, read the contract AGAINST any doc it names as its own source of truth and
+  re-state each shared rule in your own words — a contradiction here ships as "passed" and every
+  card inherits it. (This gate once passed an internally-inconsistent seam that only a later
+  cross-model review caught — catch that class HERE, at its source, where it is cheapest.) When the
+  **codex tier is USABLE**, an OPTIONAL opt-in **cross-model** check of the contract is the
+  highest-value single Codex call in a run — a different engine breaks the same-model blind spot at
+  the one artifact whose drift is most expensive downstream.
+- **Optional `ck-scenario` (when present).** Offer 12-dimension edge-case decomposition to
+  harden the seam: each case becomes an acceptance criterion + a per-type no-drift check, so the
+  contract is exhaustive before any card trusts it. Complements `/flow consistency` (it
+  *generates* cases; consistency checks *coherence*). INFORMS the gate; never auto-passes it.
+  Opt-in-with-prompt — see `claudekit-skills.md`.
+
+## Card gate (`/flow check C-NNN`)
+Mechanical: no FILL, valid status, required sections, if done -> verify boxes checked +
+evidence non-empty.
+**Challenge:**
+- Is the scope ONE thing? If it's two, split the card.
+- Does the diff touch only `## Allowed files`? Drift outside = stop, amend the card first.
+- Do request/response shapes match `flow/05-contract.md` exactly? No improvised shapes.
+- For UI cards: reviewed against `law/DESIGN.md` (tokens, affordance ladder, object-first,
+  no engine words, no emoji, no gradient on inputs/tables)?
+- **Is `## Evidence` real world-state** — a clickable URL, real curl output, a DB row — and
+  NOT "tests pass" / "code merged" / "deployed successfully"? Merge != shipped: the proof is
+  the live surface changing, verified as a user.
+- **If this card fixes a bug/regression**, the evidence includes the red→green proof that the
+  new test was actually tied to the bug (`ground-truth-gates.md` → "Bug-fix cards"), not just a
+  green run.
+
+## Cross-artifact consistency (`/flow consistency`)
+Run after the Contract gate and before building cards (advisory; never blocks the build path).
+The runner does the **precise, ID-based** passes mechanically: every PRD `FRn` is claimed by a
+card (`implements:`) and served by an interface, the success metric carries a number, no leftover
+placeholders. **You do the passes that need judgment, not string-matching:**
+- **Hollow coverage:** an `FRn` is "covered" by a card whose scope does not actually deliver it
+  (the id is referenced but the work isn't there). Mechanical coverage can be gamed by pasting an
+  id; read the card scope against the feature.
+- **Conflicting requirements:** two artifacts state incompatible things (PRD says no-login, ADR
+  decides OAuth; scope cut a feature the PRD still lists). The runner won't catch a contradiction
+  expressed in different words — you must.
+- **Cut-list contradiction:** a feature on the stage-02 cut list reappears (by name, not id) as a
+  v1 PRD feature or a card. Scope drift in disguise.
+- **Terminology drift:** the same entity named differently across artifacts (`ticket`/`issue`/
+  `request`) — the seed of producer/consumer drift the contract gate guards against.
+If you find any, report *"`consistency` passed mechanically, but <artifact> contradicts <artifact>
+on <thing>"* and let the operator decide — same posture as every other gate.
+
+**Canonical form the mechanical pass expects** (deviate and coverage silently can't map — the runner
+then prints "no FR ids found" rather than a false pass, but be aware): FR ids are **uppercase `FRn`**,
+declared in the PRD's **`## Features`** section (ids in prose or the pain table are intentionally
+ignored so a legacy mention can't inflate the set). A blank success-metric body is the gate's job, not
+this probe's (it only checks "if a metric exists, it carries a number"). When `consistency` reports
+"no FR ids found", treat it as *coverage-unverified*, not *coverage-clean*.
+
+## Constitution challenge (operator invariants — run at scope/PRD/contract)
+
+`flow.sh constitution` is the mechanical half: it proves the `flow/constitution.md` table is
+well-formed (no placeholder, every invariant has an ID) and scans any declared grep-marker. It
+**cannot** tell whether the artifact you just wrote actually *honors* the invariant — that is your
+job. After the mechanical pass, for each invariant whose `applies-at` includes the current stage,
+challenge the stage artifact against it:
+
+- Read each invariant (e.g. "all PII access is facility-scoped", "no API surface ships without a
+  `flow/05-contract.md` entry").
+- Walk the current artifact (scope / PRD / contract) and ask: does anything here *violate* it, or
+  quietly assume an exception? A contract endpoint exposing cross-tenant data violates a
+  facility-scoped invariant even though the table is structurally clean.
+- If you find a violation, report *"constitution passed mechanically, but `<artifact>` violates
+  invariant `<ID>` (`<rule>`)"* and let the operator decide — same posture as every other gate.
+
+This is **advisory and per-project**; it never auto-blocks `next`, and it does NOT replace the
+security-class Tier-C halt (a constitution rule may *restate* a security concern, but the halt is
+the enforcement). Low-noise by design: the mechanical layer is structural, the judgement is yours.
+
+## Debt (deliberate skips)
+If the operator deliberately skips/reorders a gate, ensure a line opens in `DEBT.md` naming
+the skip, the concrete exposure, and the close condition. **Security-class skips** (auth,
+admin exposure, tenancy, payments) are never silent and never your decision — the operator
+accepts the exposure in writing. In `/flow auto`, that is a Tier-C halt.

package/skills/flow/references/ground-truth-gates.md

@@ -0,0 +1,49 @@
+# Ground-truth gates
+
+At any decision point that advances, merges, or marks done, the gate condition MUST be a
+mechanical signal — not the model's opinion that it's fine. LLM self-assessment is advisory
+and used only to add color, never to pass a gate.
+
+## The signal per gate
+
+| Decision | Ground-truth signal | NOT acceptable as the gate |
+|---|---|---|
+| Stage 00-05 advance | `flow.sh next` exit 0 (no `[FILL]`, no unchecked box) | "the artifact looks complete" |
+| Card valid | `flow.sh check C-NNN` exit 0 | "I filled the card" |
+| Card behavior works | the card's `## Verify` steps RUN for real (curl/click/command + expected output) | "the code should work" / "tests would pass" |
+| Story proof | `flow.sh harness story verify <id>` -> `verify_command` exit 0 | "I wrote tests" |
+| Build merged-safe | review green (adversarial) + `flow.sh check` pass | "the diff is small" |
+| Card DONE | deploy ran + **live URL verified as a user** (world-state evidence pasted) | "merged" / "deploy succeeded" / "tests pass" |
+| Contract not drifted | contract-test card asserts every endpoint exists in live `/openapi.json` with matching shape | "backend and UI agree" (they don't, silently) |
+
+## Rules
+1. **The model never grades its own gate.** Use `flow.sh` exit codes and real command
+   output. If a tool can produce a number/exit code, that is the gate.
+2. **"Tests pass" is mid-pipeline, not done.** Done = a surface that changed in the world,
+   verified live. (buildflow rule 3.)
+3. **Self-assessment is color, not verdict.** An agent saying "looks correct" can accompany
+   a green signal; it can never substitute for one.
+4. **A red signal stops the run.** No "probably fine" override. Fix or open debt.
+5. **Capture the proof.** Paste the real curl/URL/exit into the card `## Evidence` and the
+   harness `trace` — so the next session sees ground truth, not a claim.
+
+## Bug-fix cards: prove the test was tied to the bug
+When a card's job is fixing a bug/regression (not new behavior), a passing test is not yet
+ground truth — a test written after the fix can pass without ever having exercised the bug. The
+ground-truth signal is the **red→green** pair: with the fix reverted the new test FAILS, with the
+fix restored it PASSES. Paste both runs into `## Evidence`. The reverted-failure must fail **for the
+bug's reason** — its message names the bugged behavior/output (a wrong value, a missing rejection, a
+bad status), NOT an `ImportError`/compile/setup/typo error. A revert that errors before reaching the
+asserted behavior proves nothing; if you see a collection/import/syntax error on revert, the test is
+not yet tied to the bug — fix the harness and re-run. This is a *technique for this card class*, not a
+project-wide test-first law — flow stays contract-/evidence-first. It is cleanest for
+`cli`/`library`/`skill` cards where a fix reverts in isolation. For a `web` card whose fix genuinely
+cannot revert cleanly (migration, stateful backend), the waiver is **not** agent-self-asserted: name
+the **specific** blocking dependency in `## Evidence` (e.g. "irreversible migration `0042_*`",
+"shared session store") and still paste a live `## Verify` reproduction that shows the **original
+symptom before** the fix and its absence **after** — a bare post-fix green is not the signal.
+
+## Why
+LLM-as-judge is useful for triage and prioritization but unreliable at the exact moment a
+mistake becomes expensive (a merge, a deploy, a "done"). The whole buildflow philosophy —
+"done = proof in the world" — is ground-truth gating made into a method.

package/skills/flow/references/loop-harness-2026-principles.md

@@ -0,0 +1,52 @@
+# Loop & harness engineering principles (2026)
+
+The principles `/flow` enforces during loops and autonomous runs. Distilled from current
+agentic-engineering practice and mapped to concrete flow points. We apply the **principles**;
+where a source cited a specific number, treat it as illustrative and verify in context.
+(Source: `research-report-agent-orchestration-2026.md`.)
+
+## 1. Harness-first, not prompt-first
+Quality comes from the scaffold (gates, loop control, durable state, budget), not from
+prompt tuning. `/flow` IS that scaffold: `flow.sh` gates + `harness/` durable records +
+the AUTO loop. When a run goes wrong, fix the harness (open a `backlog` item), don't just
+re-prompt. -> `flow.sh harness backlog add` (growth rule).
+
+## 2. Hard stops are mandatory
+Every loop/auto run declares caps: **max iterations per card**, **token budget**,
+**wall-clock**. Exceed any -> HALT + report, never continue silently. A loop with no
+termination criterion is an antipattern. -> see `auto-run.md` "Hard stops".
+
+## 3. Ground-truth verification at decision points
+At a gate that decides "advance/merge/done", trust a mechanical signal, not the model's
+self-assessment: `flow.sh` exit code, story `verify_command` exit, the card's `## Verify`
+run for real, the deploy + live-URL check. LLM-as-judge is advisory only, never the gate.
+-> `ground-truth-gates.md`.
+
+## 4. Adversarial verification before committing
+Before a card merges, an independent reviewer (or 3, with information asymmetry) must try
+to REFUTE it. "Must find issues; zero findings -> re-analyze." -> `adversarial-review.md`.
+
+## 5. Context isolation fights context rot
+Model accuracy degrades as the window fills. Keep each subagent's context small and scoped
+(task + files + acceptance + relevant law excerpts — no session history), and push durable
+state OUT to `harness/` (external memory) and `flow/` + `cards/` (on-disk artifacts). One
+card = one fresh, small context. -> `agent-detection.md` context rules.
+
+## 6. Spec/contract-first prevents drift
+The #1 AI-build failure is producer/consumer drift (backend ships one shape, UI assumes
+another, both green). The contract (stage 05) written before code, asserted against the
+live spec by the contract-test card, is the cheap fix. "Contract is the seam."
+
+## 7. Make truncation legible
+If a run bounds coverage (top-N cards, skipped a gate, sampled), SAY so. A silent cap reads
+as "covered everything". Debt is the ledger for deliberate skips -> `debt-and-halts.md`.
+
+## Mapping to flow points
+| Principle | Enforced at |
+|---|---|
+| Hard stops | `/flow auto` loop (iteration/token/time caps) |
+| Ground-truth | every gate decision (`flow.sh` exit, verify runs, live check) |
+| Adversarial | Review step before merge (`code-reviewer` / `bmad-code-review`) |
+| Context isolation | per-card scoped subagent brief + `harness/` external memory |
+| Contract-first | stage 05 + contract-test card |
+| Legible truncation | `DEBT.md` + `AUTO-LOG.md` + announce path/verdict |

package/skills/flow/references/mode-work.md

@@ -0,0 +1,37 @@
+# Mode: work (AI drafts, gates still bind)
+
+`MODE` file at project root (default `teach`). Set with `/flow mode work`.
+
+- **teach** — the operator writes every artifact; you only gatekeep. Default.
+- **work** — you interview the operator ONCE, draft stages 00-05 yourself, pause only for
+  scope sign-off, deliver the card set as one summary. **Gates and done-rules are identical
+  to teach** — you still pass every gate, you just also author.
+
+## The work-mode shape (interview once -> draft -> one pause -> summary)
+
+1. **Interview once.** Ask a single tight batch (use `AskUserQuestion`): the idea in one
+   line, who has the pain (a real named person/group), the rough budget/time, the stack if
+   they have a preference, and the one channel for the first users. Don't drip questions
+   across stages.
+2. **Draft 00 -> 01 -> 02.** Fill idea, do real research (delegate to `researcher` per
+   `agent-stage-mapping.md` — actually open competitors, quote real complaints with links),
+   and produce the scope table with honest Impact + Grade. Run each gate with `flow.sh next`.
+3. **ONE scope pause.** Stop at the Scope gate (stage 02). Present the GO/KILL + cut list +
+   any C-feature path decisions and get explicit sign-off. This is the only mandatory pause
+   in work mode — scope is the operator's call, and killing here is cheap.
+4. **Draft 03 -> 05.** PRD (numeric metric, pain->feature mapping), ADR (delegate to
+   `architect`/`bmad-create-architecture`), Contract (the seam; consider `bmad-spec` kernel).
+   Run each gate.
+5. **Deliver the card set as one summary.** After stage 05 passes, run `/flow card` to
+   create the cards, fill their scopes, and present the whole set + build order + which are
+   parallel-safe (`/flow ready`) in a single summary for the operator to review.
+
+## Rules that still hold in work mode
+- Every gate must pass mechanically (`flow.sh`) AND semantically (`gate-rules.md`). Drafting
+  does not lower the bar — self-challenge before presenting (you are now the author AND under
+  review, so apply the adversarial lens to your own draft).
+- Research must be real (opened competitors, quoted complaints with links) — no fabrication.
+  This is the highest-risk stage for an AI author; verify every quote has a source.
+- Scope honesty: do not grade-launder your own C features to B. Call C a C, justify the path.
+- Done is still world-state evidence; you cannot mark a card done without real proof.
+- Write durable records (intake/decision/story) as you go, same as teach mode.

package/skills/flow/references/project-types.md

@@ -0,0 +1,42 @@
+# Project types — adapting the gates to what you're building
+
+`/flow` was born web-shaped. Set the type with `flow.sh project-type <web|cli|library|skill>`
+(stored in `PROJECT_TYPE`, default `web`). The type adapts three things: what the Contract
+"seam" is, the standard card sequence, and — most importantly — what **done-evidence** means.
+The *spirit* of every gate is unchanged ("done = proof in the world", "contract before
+code"); only the shape of the proof changes.
+
+## Per-type table
+
+| Type | Contract seam (stage 05) | Done-evidence (the real proof) | Card sequence |
+|---|---|---|---|
+| **web** | HTTP endpoints (Method/Path/Auth/Request/Response); OpenAPI served | a live deployed URL + real curl output | scaffold+`/healthz` -> vertical slice (endpoint+page) -> backend -> contract-test -> UI mock -> frontend -> e2e |
+| **cli** | commands + flags + output shapes + exit codes | the tool **installs and a real invocation returns the expected output + exit code** | scaffold+one real command -> subcommand groups -> tests -> install smoke on a clean dir |
+| **library** | the public API surface (exported functions/types + their shapes) | the **public API imports + a usage example runs + coverage threshold met** | scaffold+core API -> rounds of API -> tests -> a runnable usage example -> publish dry-run |
+| **skill** | the commands + files the agent reads (SKILL.md surface) | **installed into `~/.claude/skills` + a real run reaches its own done-definition** | scaffold+one runnable command -> references/law -> install -> a dogfood run |
+
+## What stays the same (all types)
+- Every PRD feature maps to an interface; every interface has its shapes written BEFORE code.
+- "Tests pass" / "merged" is mid-pipeline, never done — done is the type's real-world proof above.
+- The contract is the seam: producers build TO it, consumers FROM it; amend the contract first.
+
+## Gate-wording note (known web-flavoring — see backlog #4)
+The stage-05 gate text still says "endpoint" and "auth (public/token/admin)". For non-web
+types, read "endpoint" as "interface/command" and replace the auth column with
+"writes/side-effects" (the stage-05 preamble explicitly licenses this adaptation). The
+`web`-only OpenAPI/Swagger rule is N/A for cli/library/skill — the equivalent "no drift"
+check is the per-type done-evidence actually passing.
+
+## Legitimate gate-skips
+When a gate genuinely doesn't fit your type (e.g. the Research market-research items for an
+internal tool), record it and skip honestly:
+```
+/flow debt add "skip 01-research" "<exposure>" "<close-before condition>"
+/flow skip 01-research --reason "internal tool, no public market"
+```
+`skip` advances ONLY when an open DEBT line **names that exact stage** AND the reason is
+non-security-class; `planning_complete` then tolerates that stage so `/flow card` is not
+blocked forever. Guards (in order): the **contract (05) can never be skipped** — it is the
+seam, adapt it per project type instead; a **security-class reason HALTS** (auth/authz/
+admin/tenancy/payments/credential/permission/role/rbac/login/pii/data/migration/validation —
+operator-only); and the DEBT must name the stage (an unrelated open DEBT will not unlock it).

package/skills/flow/references/stage-state-machine.md

@@ -0,0 +1,47 @@
+# Stage state machine
+
+How `/flow` advances. The runner computes "current stage" as the highest-numbered stage
+file that exists in `flow/`. `/flow next` gate-checks that stage and, on pass, unlocks the
+next one. Planning is complete only when **all six** stage gates are clean; only then does
+`/flow card` unlock.
+
+```
+(no flow/)                      --/flow next-->  flow/00-idea.md        [stage 00 unlocked]
+flow/00-idea.md   gate clean    --/flow next-->  flow/01-research.md    [stage 01 unlocked]
+flow/01-research.md gate clean  --/flow next-->  flow/02-scope.md       [stage 02 unlocked]
+flow/02-scope.md  gate clean    --/flow next-->  flow/03-prd.md         [stage 03 unlocked]
+flow/03-prd.md    gate clean    --/flow next-->  flow/04-adr.md         [stage 04 unlocked]
+flow/04-adr.md    gate clean    --/flow next-->  flow/05-contract.md    [stage 05 unlocked]
+flow/05-contract.md gate clean  --/flow next-->  PLANNING COMPLETE      [/flow card unlocks]
+all 6 gates clean               --/flow card-->  cards/C-001.md, C-002.md, ...
+cards built + verified          --/flow check->  per-card exit gate (status done + evidence)
+all cards done                  --/flow retro->  one line in RETRO.md
+```
+
+A gate FAIL never advances; it lists every unchecked box and `[FILL]` with line numbers.
+**Kill is also a terminal state** — stopping at any gate (especially Scope) is a valid,
+honored outcome, not a failure of the flow.
+
+## What each artifact must contain (so the gate is meaningful)
+
+| Stage | File | Must contain |
+|---|---|---|
+| 00 Idea | `flow/00-idea.md` | 3-sentence pitch (who/pain/what) + one named real person with the pain |
+| 01 Research | `flow/01-research.md` | 3 opened competitors, 3 quoted complaints w/ links, real prices, ONE named first-10 channel, switch reason, free-vs-hard |
+| 02 Scope | `flow/02-scope.md` | every feature Impact(H/M/L)+Grade(A/B/C), C-justification path, cut list, GO/KILL |
+| 03 PRD | `flow/03-prd.md` | numeric success metric, pain&gain mapping table, user-action->observable-result features |
+| 04 ADR | `flow/04-adr.md` | decisions with why+rejected covering storage/auth/deploy, NOT-doing list |
+| 05 Contract | `flow/05-contract.md` | every feature->endpoint, request+response shapes, auth per endpoint |
+| Card | `cards/C-NNN.md` | one-thing scope, deps, allowed files, verify steps, named done-evidence, pasted evidence when done |
+
+## Shipping stages live inside cards
+Build -> Review -> Deploy -> Verify-live are NOT `/flow next` stages. They happen inside
+each card: the `## Verify` checklist (run for real) and `## Evidence` (world-state proof).
+Card sequence (scaffold/CI -> vertical slice -> backend -> contract-tests -> UI mock ->
+frontend -> e2e) is governed by `law/CLAUDE.md`.
+
+## Runner contract
+- `flow.sh` exit `0` = pass/advanced, `1` = gate fail or usage error.
+- Reads/writes `flow/`, `cards/`, `MODE`, `RETRO.md`, and seeds `DESIGN.md` once, under `FLOW_PROJECT_ROOT` (default `$PWD`).
+- `DEBT.md` is written by the **semantic layer** (Claude), not the runner — the runner only reminds.
+- Templates are read-only from `<skill>/_templates`; never edited during a run.

package/skills/flow/references/ui-patterns-tcr.md

@@ -0,0 +1,49 @@
+# 7 UI patterns + T-C-R framework
+
+For AI-product UIs. Pick a pattern, then layer T-C-R (Transparency / Control / Recovery) —
+the load-bearing frame for trustworthy agentic UI. (Source: ai20k workshop-0422.)
+
+## The 7 patterns
+| # | Pattern | Use for |
+|---|---|---|
+| 1 | **Chat + context panel** | AI TA, RAG chatbot, Socratic tutor (conversation left, evidence right) |
+| 2 | **Upload -> dashboard** | survey analysis, report summarizer, invoice extractor |
+| 3 | **Query -> structured result** | text-to-SQL, digital-twin Q&A (NL -> table/chart) |
+| 4 | **Wizard + inline audit** | syllabus/compliance/onboarding (multi-step form, AI checks each step) |
+| 5 | **Draft -> approve -> send** | emergency comms, email assistant (AI drafts, human approves, system sends) |
+| 6 | **Queue + approval** | moderation, grading at scale, contract review (batch AI labels, human clears) |
+| 7 | **Real-time streaming** | voice Q&A, live transcription (live pipeline) |
+
+**Meta-pattern:** Pattern 1 with a swappable panel covers most cases (panel = sources->RAG,
+progress->long agent, reasoning->research, chart->data Q&A, queue->inbox).
+
+## Priority rules to choose a pattern (top wins)
+irreversible action -> **5** · batch -> **6** · streaming -> **7** · multi-step form -> **4**
+· file upload -> **2** · text->chart/table -> **3** · text->text+sources -> **1** ·
+ambiguous -> **1 + pick the panel payload**.
+
+## T-C-R (add to whatever pattern you chose; compounds when added in order)
+- **T = Transparency.** Show what the AI is doing: status line ("Đang tra cứu 3 nguồn..."),
+  sources panel, confidence traffic-light (green >0.8, amber 0.5-0.8, red <0.5), visible
+  SQL/reasoning/plan, which model.
+- **C = Control.** Let the user stop/edit/override BEFORE an irreversible act: abort button,
+  edit-before-execute, dry-run preview, bulk + keyboard shortcuts, pin/clear.
+- **R = Recovery.** Pre-flight validation + post-hoc repair: validate input before the call,
+  retry, undo, "flag as bad" (becomes a training signal), regenerate, preview+cancel.
+
+> If a UI element doesn't map cleanly to T, C, or R, rewrite it until it does. This frame is
+> load-bearing — it's what makes an agentic UI trustworthy for non-technical users.
+
+## T-C-R per pattern (quick matrix)
+| Pattern | T | C | R |
+|---|---|---|---|
+| 1 Chat+panel | sources panel, streaming status, confidence dot | stop streaming, edit last msg, clear | error-bubble retry, thumbs-down |
+| 2 Upload->dash | parse/extract progress, per-insight source | cancel, preview modal for big files | file pre-flight, "try another", keep-previous undo |
+| 3 Query->result | "view SQL", confidence badge, rows/ms/model | edit query before run, confirm destructive | retry, "rephrase" feeds error back, history |
+| 4 Wizard+audit | per-field ok/warn/fail + reason | back/forward no data loss, save draft, override warning | validate per step, preview+edit before submit |
+| 5 Draft->send | confidence/section, recipient preview | mandatory preview (no generate-and-send), edit any field | "sent - undo" 10s, retry, keep draft on fail |
+| 6 Queue | confidence dot/item, 1-line reason, counts | bulk + shift-click, J/K/A/R keys, filter by confidence | undo stack, "flag for review" not reject, re-surface |
+| 7 Streaming | live status, token-by-token, latency | stop aborts, pause/resume | auto-reconnect (max 3), preserve buffer, manual restart |
+
+Combine with `law/DESIGN.md` (tokens, affordance ladder, object-first) — T-C-R is the
+behavior frame, DESIGN.md is the visual law. Both bind every UI card.

package/skills/flow/runner/flow.cmd

@@ -0,0 +1,18 @@
+@echo off
+rem flow gate-engine launcher for Windows shells (PowerShell / cmd / Codex).
+rem Codex and PowerShell resolve a bare `bash` to WSL (C:\WINDOWS\system32\bash.exe),
+rem which cannot read C:/ paths and fails with "No such file or directory".
+rem This finds Git Bash and runs the runner with a forward-slash path it accepts.
+setlocal
+set "SELF=%~dp0flow.sh"
+set "SELF=%SELF:\=/%"
+set "GB=%ProgramFiles%\Git\bin\bash.exe"
+if not exist "%GB%" set "GB=%ProgramFiles(x86)%\Git\bin\bash.exe"
+if not exist "%GB%" set "GB=%LOCALAPPDATA%\Programs\Git\bin\bash.exe"
+if not exist "%GB%" (
+  echo flow: Git Bash not found - install Git for Windows ^(https://git-scm.com^) so the gate engine can run.
+  exit /b 1
+)
+"%GB%" "%SELF%" %*
+rem propagate the gate engine's exit code (0/1) - it is flow's ground truth
+exit /b %ERRORLEVEL%