@manhquy/flow-skill 0.7.0 → 0.7.2

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

@@ -0,0 +1,37 @@
+# Shared gate rules — open decisions and material authority
+
+Unique home for OD / material-authority. Stages 02 / 03 / 05 point here; do not copy.
+
+## Material authority
+
+If materially different externally observable product choices remain open (quota,
+identity key, tenancy model, response contract, enforcement owner, …), **stop** —
+list the choice and consequences. Configurable defaults are not authority.
+
+If the artifact invents policy (who can access what, retention, billing rules) with
+no prior operator/ADR authority, stop and list Decision-required items.
+
+Access/effects (public/token/admin, writes) that encode product policy without
+operator authority → stop; do not invent tenancy/auth from convenience.
+
+## Assumption vs open decision
+
+Read `## Assumptions`. A bullet that encodes product law (who can access what,
+tenancy, retention, billing, enforcement owner) with no operator/ADR authority is
+an **open decision or a stop**, not a silent default — move it under
+`## Open decisions` (a line like `- [ ] which tenant key?`) or halt. Do not invent
+auth/tenancy/retention/billing to clear `[FILL]`.
+
+Contract has no `## Assumptions` section; do not invent one. Access/effects or
+shared shapes that encode product law (tenancy, auth, retention, billing) with no
+operator/ADR authority are an **open decision or a stop** — add a
+`## Open decisions` bullet or halt.
+
+## Open decisions — mechanical
+
+**More than 5 markdown bullets under `## Open decisions` fails `scan_gate`.**
+Leftover `- [ ]` still fails boxes. Clarify (`references/clarify.md`) is opt-in,
+never a `next` prereq.
+
+If the section is a pile after that floor, assume or cut rather than interview
+everything. Offer clarify when any open decision remains.

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

@@ -13,7 +13,7 @@ and used only to add color, never to pass a gate.
 | 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" |
+| Card DONE | per-type world-state evidence pasted (deployed URL for web; install+run for cli/library/skill) | "merged" / "deploy succeeded" / "tests pass" |
 | Card DONE (mechanical floor) | `flow.sh check` / `card done`: `## Evidence` multi-signal score ≥2 (URL + curl/command/test-log/path/DB/skill categories; denylist example.com etc.) | process-only prose (PR approvals, CI green, release notes alone); empty/placeholder |
 | Dep ready / parallel | `ready` + graph deps-met: dep `status=done` **and** same Evidence multi-signal floor | hand-edit `status: done` with hollow Evidence |
 | Auto activation | risk set valid + current Stage 05 `semantic_gate` receipt (`attestations.md`) | prose “planning looks done” |

package/skills/flow/references/host-agnostic-parallel.md

@@ -0,0 +1,54 @@
+# Host-agnostic parallel occupancy
+
+Flow requires **no named multiplexer**. Parallel cards are a ready-gate +
+worktrees + host-owned placement + world-state fan-in. Absence of Herdr, tmux,
+in-process `Task`, or any other host **never fails a gate** and never changes
+`flow.sh` exit.
+
+Herdr and tmux appear below only as **examples, never as a dependency** or a
+first-class adapter.
+
+## Degrade ladder
+
+| Rung | Primitive already in the process | Who binds occupants | Who waits |
+|---|---|---|---|
+| **0** | In-process subagents / `Task` | Hosting agent; cwd = the card's worktree | Host `Task` join |
+| **1** | Operator extra terminals / tabs | Human pastes the print-enter block | Human |
+| **2** | Process is **already inside** a mux (`HERDR_ENV=1` / `TMUX` set) | That mux's **own** skill/CLI; flow does not wrap or detect it | That mux's own wait |
+| **3** | None of the above, or `/flow ready` overlap | Serial: one card | Hosting agent, one at a time |
+
+Rung 2 is opt-in by the mux's own environment injection, never by `PATH`.
+Inside-mux probe is the mux's own env (`HERDR_ENV=1`, `TMUX`), never
+`command -v herdr` from outside (a CLI can talk to a same-uid socket without
+`HERDR_ENV`). Absence of rungs 0–2 is the default path, not a degrade footnote.
+
+## Gate parity
+
+Host `idle` / `done` / `blocked` is **not a card pass**. `flow.sh check` still
+judges, and it must run **in the card's worktree** (parent-tree check of main
+is a false fail/pass). Screen output is not evidence.
+
+Keep the four "blocked" senses distinct:
+
+| Sense | Meaning | Home |
+|---|---|---|
+| **host-blocked** | mux/pane approval chrome or occupant stuck | the host |
+| **subagent-BLOCKED** | scoped subagent status protocol | `agent-detection.md` |
+| **ready-blocked** | deps unmet or allowed-files overlap | `flow.sh ready` |
+| **Tier-C security halt** | security-class exposure; operator DEBT | `auto-run.md` |
+
+Mixing them auto-answers a payments card or auto-halts a yes/no prompt.
+
+## File-is-the-wait
+
+The **HOST waits** (Task join / human / the mux's own wait). `flow.sh` **never waits on or polls** another agent. Fan-in is world-state: re-invoke `check` in
+the card worktree after the host's wait returns.
+
+## Forbidden (ADR-0001; not a nit)
+
+`flow.sh` must not exec host control CLIs (`herdr agent start`, `herdr agent wait`, `herdr agent prompt`, `herdr server stop`, `tmux send-keys`, and equivalents).
+Forbidden by name: `mux-up`, `mux-run-wave`, `mux-proxy`. No screen output as
+evidence. No hook install into `~/.claude` or `~/.omp`. No long-lived socket subscribe (`events.subscribe`). `flow.sh` never spawns agents; placement is print-enter or the host's own Task/mux.
+
+Own-runtime / own-PTY / own-wait is a successor ADR plus a separate product,
+not a card in this skill.

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

@@ -2,17 +2,20 @@
 
 `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
+- **teach** — the operator writes every artifact; the host only gatekeeps. Default.
+- **work** — interview the operator ONCE, draft stages 00-05, 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.
+  to teach** — every gate still passes; the host also authors.
 
 ## 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.
+1. **Interview once.** One tight batch — numbered questions, not a drip across stages:
+   1. Idea in one line?
+   2. Who has the pain (a real named person/group)?
+   3. Rough budget/time?
+   4. Stack preference, if any?
+   5. One channel for the first users?
+   Host-neutral: use whatever ask/prompt surface the host has.
 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`.
@@ -33,8 +36,8 @@
 
 ## 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).
+  does not lower the bar — self-challenge the draft before presenting. Self-challenge is
+  color, not a verdict: it never substitutes for `flow.sh` + `gate-rules.md`.
 - 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.
@@ -43,5 +46,5 @@
   can still halt or add a bullet (a policy-encoding `## Assumptions` line with no operator/ADR
   authority is an open decision, not a silent default). Never invent auth / tenancy / retention
   / billing to clear FILL.
-- Done is still world-state evidence; you cannot mark a card done without real proof.
+- Done is still world-state evidence; a card cannot be marked done without real proof.
 - Write durable records (intake/decision/story) as you go, same as teach mode.