@manhquy/flow-skill 0.1.0-rc.1

package/skills/flow/references/adversarial-review.md

@@ -0,0 +1,197 @@
+# Adversarial review (the Review gate)
+
+Before a card merges, it is reviewed by a reviewer whose job is to **find issues** — not to
+bless. "No 'looks good' allowed. Zero findings triggers a halt: re-analyze, or explain why
+nothing was found." (BMAD adversarial-review pattern.) Prefer `bmad-code-review` when
+present; else `code-reviewer`; else run the three lenses yourself as separate passes.
+
+## Security-class lens selection
+
+When a card is **security-class** (auth, authorization, admin exposure, tenancy, payments,
+data migration, removing/weakening validation — same trigger as `auto-run.md` Tier-C),
+the Review gate uses the **`security-reviewer` AGENT** (STRIDE/OWASP, secrets, injection,
+SSRF) as the primary acceptance lens, **layered with `code-reviewer`**. Non-security cards
+stay with the generic `code-reviewer` — no change to that path.
+
+**Agent vs skill:** `security-reviewer` is an **AGENT** (`Task(subagent_type="security-reviewer")`)
+invoked in subagent isolation — it sees the diff, contract, and acceptance only. `ck-security`
+is a **SKILL** (main-context Skill tool, no subagent isolation); it may be used as an optional
+inline pass by the orchestrator, but it is **never** the delegated review subagent.
+
+**Offer `ck-security` on a security-class card (opt-in-with-prompt).** When a card is
+security-class and the `security-reviewer` agent is absent (or as an extra threat-model pass),
+offer the `ck-security` SKILL (STRIDE+OWASP attacker personas) — the operator confirms; it is not
+auto-fired. Its output INFORMS triage and **never auto-passes the Tier-C HALT** (see the Critical
+note below). After it runs, record the lazy durable metric via `flow.sh harness intervention add`
+(the wired-gate skill-telemetry — `claudekit-skills.md` §"Lazy capture"). See `claudekit-skills.md`.
+
+**Portability degrade rung** (detect-first, gate identical on every rung):
+1. `security-reviewer` AGENT present → run it layered with `code-reviewer` (primary path).
+2. `security-reviewer` absent → `code-reviewer` runs an explicit STRIDE/OWASP checklist
+   covering the Tier-C keyword list (auth, authz, tenancy, payments, injection, secrets, SSRF).
+3. Neither available → inline security review against the Tier-C keyword list by the orchestrator.
+
+**Gate parity — the lens INFORMS triage; it NEVER auto-fails or auto-passes a card.** A
+`security-reviewer` "looks fine" verdict is advisory evidence fed into the same triage table
+below. The Review gate still decides.
+
+**Critical: the lens NEVER releases the Tier-C operator HALT.** The security-class HALT
+(`auto-run.md:13,57`) is triggered by CLASSIFICATION and resolved ONLY by written operator
+acknowledgment in `DEBT.md`. A `security-reviewer` clean verdict can NEVER substitute for, or
+auto-release, that HALT — it is advisory evidence for the operator, not a gate key.
+
+**No-defang rule applies to the security dispatch.** Hand the `security-reviewer` the diff,
+the contract, and the card's acceptance — never add "don't flag X" or "treat as minor at
+most". The same defang prohibition above governs the security dispatch equally.
+
+## Language-specialist lens selection
+
+When a card's changed files have a detectable primary language, the Review gate adds the
+matching **language-specialist AGENT** as a layered lens alongside `code-reviewer`:
+
+- `.ts / .tsx / .js / .jsx` extensions → **`typescript-reviewer` AGENT** (type-safety, async
+  correctness, Node/web idioms).
+- `.py` extensions → **`python-reviewer` AGENT** (PEP 8, type hints, Pythonic idioms,
+  security via Bandit lens).
+- No dominant language-match → generic **`code-reviewer`** only (no specialist layer).
+
+Detect the primary language from the card's `## Allowed files` list (majority extension wins;
+mixed-language cards with no majority default to `code-reviewer`).
+
+**The specialist is LAYERED with `code-reviewer`** — it is an additional reviewer, not a
+replacement. Running both gives two review angles on the same diff; the gate's triage table
+weighs findings from both.
+
+**Composes with the security lens.** A security-class TypeScript card triggers
+`security-reviewer` + `typescript-reviewer` + `code-reviewer` — all three run. The lenses
+are additive. Security-class detection (`## Security-class lens selection`) and language
+detection are independent: each is evaluated separately, and the resulting set is the union.
+
+**Portability degrade rungs** (detect-first, gate identical on every rung):
+1. Language-specialist AGENT present → run it layered with `code-reviewer` (primary path).
+2. Specialist absent → `code-reviewer` runs an explicit checklist targeting the primary
+   language's known failure modes (e.g. TypeScript: `any` escapes, unhandled promise
+   rejections, missing strict-mode; Python: bare `except`, missing type hints, mutable
+   default args).
+3. Neither available → inline language-aware checklist run by the orchestrator.
+
+**Gate parity — the specialist lens INFORMS triage; it NEVER auto-fails or auto-passes a
+card.** A `typescript-reviewer` or `python-reviewer` verdict is advisory evidence fed into
+the same triage table below. The Review gate still decides. A clean specialist verdict never
+substitutes for the acceptance audit or the three-layer review structure.
+
+**No-defang rule applies to the specialist dispatch.** Hand the specialist the diff, the
+contract, and the card's acceptance — never add "don't flag X" or "the team already chose
+this pattern". The same defang prohibition in the next section governs every lens equally.
+
+## Don't defang the reviewer (controller-side input)
+
+The "must find issues" rule above governs the reviewer's **output**. It is defeated at the source if
+you hand the reviewer a **poisoned prompt**. When you construct a review dispatch, you may not
+pre-judge its findings:
+
+- Never write "don't flag X", "treat it as Minor at most", "the plan already chose this", or any
+  steer that tells the reviewer what NOT to find. If you believe a finding would be a false
+  positive, let the reviewer raise it and adjudicate it in triage — do not pre-empt it.
+- The card's own example/scaffold code is a starting point, not evidence its weaknesses were
+  intentional. Do not present it to the reviewer as "the chosen design".
+- Hand the reviewer the diff as a file (or scoped repo read), the contract, and the card's
+  acceptance — not your opinion of the diff. The reviewer's lens is acceptance + contract + the
+  three hunts, nothing you added to spare yourself a review loop.
+
+A reviewer told what not to find is not adversarial. If the dispatch you are writing contains any
+"do not flag" steer, stop — that is the failure this gate exists to prevent, one layer up.
+
+## Three layers (information asymmetry — each sees less, so each catches different things)
+
+| Layer | Sees | Hunts for |
+|---|---|---|
+| **Blind Hunter** | the diff ONLY (no context) | bugs visible on the diff surface; smells |
+| **Edge Case Hunter** | diff + repo read access | every branch/boundary/empty/error path |
+| **Acceptance Auditor** | diff + `flow/05-contract.md` + `flow/03-prd.md` + the card | contract-shape violations, PRD acceptance gaps, missing specified behavior |
+
+Run them as separate scoped subagents (or separate passes) so no single context biases the
+others. The Acceptance Auditor is the one that catches producer/consumer drift — it checks
+the diff's shapes against the contract.
+
+## Optional 4th lens — Codex cross-MODEL reviewer (different vendor, not just different context)
+
+The three lenses above differ by *information* but share one *model* (Claude) → correlated blind
+spots. When the codex tier is USABLE (`codex-integration.md`), add a **cross-model** lens: run
+`codex-companion.mjs review|adversarial-review [--base <ref>] [--scope working-tree|branch]`
+(review/adversarial-review go through `codex-companion.mjs` — the `codex:codex-rescue` subagent
+only forwards to `task`, so it is NOT a review path). A different engine (GPT-5.x) catches failure modes a
+same-model panel structurally can't — cross-model review markedly outperforms same-model
+self-review (gemini-cli study: 43% → 91% merge-ready), and same-model judges carry systematic
+self-bias.
+
+- **It INFORMS, never decides.** Codex returns a `ReviewResult` (`verdict`, `findings[]` with
+  severity/confidence, `next_steps`). Feed its findings into the SAME triage below. The gate still
+  judges; a Codex `needs-attention` never auto-fails a card and a Codex `approve` never auto-passes
+  one. Apply the "do not blindly accept findings" rules to Codex output too.
+- **When to spend it (cost gate — the SAME three triggers as `codex-integration.md`).** Run the
+  Codex lens only on: a **security-class card review** (which also triggers the `security-reviewer`
+  specialist lens — see `## Security-class lens selection` above), a **two-strikes** review deadlock, or an
+  **explicit operator opt-in** — and only when the tier is USABLE. A suspicious same-model "all
+  clear" (zero findings) is a good reason to *ask the operator to opt in* to a cross-check, **not**
+  an automatic trigger — auto-firing on every zero-findings card would blow past the cost gate.
+  Codex calls are billable (`codex-integration.md` §Cost gate).
+- **Record the durable metric (S2).** Log whether the cross-model lens AGREED or surfaced a class
+  the same-model panel missed: `flow.sh harness intervention add` (disagreement = a caught miss) or
+  `intake`. This feeds the cross-model-catch-rate in `docs/quality-metrics.md` — the measured
+  justification for keeping the lens.
+
+## Optional 5th lens — Antigravity (Gemini-3) cross-vendor reviewer (a third vendor)
+
+When the Antigravity tier is USABLE (`antigravity-integration.md`), add Gemini-3 as a further
+cross-vendor lens — the SAME three triggers and cost/data gate as Codex. With Claude × GPT-5.x ×
+Gemini-3 you get a **three-model** gate; three vendors rarely share one blind spot. Run it AFTER
+Codex on a two-strikes deadlock (a third independent engine before escalating to the operator), or
+in parallel on a security-class card / explicit opt-in. **Usability is stricter here:** `agy`'s exit
+code lies (exit 0 + empty stdout even when unauthenticated), so route ONLY on non-empty expected
+output, prefer the **interactive** path (IDE Agent Manager / real `agy` terminal, paste the
+`ReviewResult` back), and treat an empty Gemini result as **"review unavailable", never an approval**.
+Same parity rule: it INFORMS, never auto-passes/auto-fails. Log the same durable metric.
+
+## Optional lens — review-pr (PR-context, when the card ships as a GitHub PR)
+
+The three layers + cross-model lenses all review a **diff**. When the card's change lives as a
+**GitHub PR**, offer the `review-pr` SKILL as an additional lens — it adds the PR-context checks a
+diff-only review structurally can't see: duplicate prior work, AI-slop patterns, breaking-change
+detection across the whole PR, and CI-blocker triage (with optional `--fix`). It is **distinct from
+the wired `code-reviewer` agent** (diff lens), not a twin — see `claudekit-skills.md`.
+
+- **Opt-in-with-prompt.** Offer it when a PR exists; the operator confirms. Do not auto-fire it on
+  every card, and never on a local-only (no-remote) build.
+- **Gate parity — INFORMS, never decides.** `review-pr` findings feed the SAME triage below; a
+  clean `review-pr` never auto-passes a card and a flagged one never auto-fails it. The Review gate
+  still judges. The "do not defang the reviewer" rule applies — hand it the PR, not your verdict.
+- **Lazy durable metric (S2).** After it runs, record via `flow.sh harness intervention add`
+  whether it caught a class the diff lenses missed (this is the wired-gate skill-telemetry — see
+  `claudekit-skills.md` §"Lazy capture").
+
+## Triage
+Group every finding by severity x actionability:
+- **Must-fix (correctness/contract/security)** -> Tier-B repair by a FRESH subagent before merge.
+- **Should-fix (maintainability)** -> fix now if cheap, else note.
+- **Observation** -> record, proceed.
+Two-strikes: a second red review on the same card -> try the next USABLE cross-vendor engine
+(Codex, then Antigravity) as a fresh-engine pass; if none usable or still red, escalate to the
+operator, don't loop.
+
+## Apply your own decision rules (do not blindly accept findings)
+- Validate each finding against what the code actually does and protects. "Theoretically
+  yes, practically no" findings are documented, not blindly fixed.
+- A verified decision is not reversed by a review opinion alone — only by a NEW issue the
+  verification missed, or changed context. Surface conflicts to the operator with the source.
+- Security-class findings (auth/authz/data/payments) are never waved through — they are
+  Tier-C: operator decides, in writing (`debt-and-halts.md`).
+- No performative agreement. When a finding lands, do not answer "you're absolutely right" /
+  "great catch" and then comply — that reflex launders a wrong finding into a change. State the
+  adjudication: confirmed (→ fix) or refuted-with-reason (→ documented). Agreement is a verdict you
+  reach, not a courtesy you extend.
+
+## Output
+A short report: findings by layer, triage, and the verdict (green / repair-needed /
+escalate). On green, proceed to `flow.sh check` -> merge -> deploy -> live verify. Record a
+`trace`; on a red that overrode an agent, record an `intervention`.

package/skills/flow/references/agent-detection.md

@@ -0,0 +1,88 @@
+# Agent detection & priority
+
+`/flow` orchestrates whatever specialist agents exist in the host, and degrades to
+built-in behavior when none are present. It stays portable: rich where agents exist,
+unbroken where they don't.
+
+## Detection (at runtime, by the skill = Claude)
+
+You already know which agents and skills the host exposes (the Task tool's
+`subagent_type` registry + the available Skills list). Detect by checking that registry —
+do NOT assume. Also glob for project-local definitions when unsure:
+- ck: agents: `.claude/agents/*.md` (project) and the host agent registry.
+- bmad skills: the Skills list (`bmad-*`) and `.claude/skills/bmad-*`.
+
+## Priority order (operator chose: ck: first, bmad alternative)
+
+For each stage, pick the FIRST available:
+1. **ck: agent** (primary) — planner, researcher, architect, fullstack-developer, code-reviewer, typescript-reviewer, python-reviewer, tester, ui-ux-designer, docs-manager, git-manager, debugger, scout.
+2. **bmad-* skill** (alternative) — bmad-prd, bmad-create-architecture, bmad-spec, bmad-create-story, bmad-dev-story, bmad-code-review, bmad-check-implementation-readiness, bmad-market-research, bmad-technical-research, bmad-qa-generate-e2e-tests.
+3. **built-in fallback** — you (Claude) do it inline, or spawn a generic `Explore`/`general-purpose` agent. Output shape must match the agent path so the gate is identical.
+
+## Codex — the cross-vendor second engine (a tier that crosses the ladder, not just sits under it)
+
+When the `openai-codex` plugin is present, a **fourth path** unlocks: **Codex (OpenAI GPT-5.x)**.
+Codex is not "tier 4 below built-in" in the linear sense — it is a *cross-vendor engine* used at
+three specific moments where a genuinely different model is worth more than another Claude pass.
+Full seam (invocation surfaces, shapes, cost gate): **`references/codex-integration.md`**.
+
+- **Rescue / escalation (default use).** When a same-model agent returns BLOCKED a second time
+  (two-strikes), hand the scoped brief to `codex:codex-rescue` BEFORE escalating to the operator.
+  A different engine breaks deadlocks correlated blind spots can't. This *replaces* "fresh subagent
+  or escalate" as the preferred second strike when Codex is available.
+- **Cross-model review.** At the Review gate, run Codex as an extra adversarial lens
+  (`codex-companion.mjs review|adversarial-review`) — see `adversarial-review.md`. It INFORMS
+  triage; the gate still judges. Never let Codex's verdict auto-pass or auto-fail a card.
+- **Opt-in primary drafter.** The operator MAY select Codex as the primary drafter for a
+  research or build stage (`codex:codex-rescue --write` / `codex-companion.mjs task --write`).
+  Default stays ck:; the identical stage gate judges the Codex-drafted artifact.
+
+**Detection (I1) — installed ≠ usable.** The codex tier has two states (`codex-integration.md` §I1):
+**INSTALLED** (`codex:codex-rescue` in the registry OR the `openai-codex` plugin dir exists) and
+**USABLE** (INSTALLED + a non-billable `codex-companion.mjs setup --json` check reports
+`ready` + `auth.loggedIn`; NOT `status`, which has no auth field — see `codex-integration.md`).
+**Only select Codex when USABLE.** INSTALLED-but-not-usable (no auth / unreachable — common in
+headless/CI) or absent → **degrade** to ck:→bmad→built-in, announce "codex tier unavailable —
+degraded to <path>", record the reason. Never route to Codex on mere presence: that would spend a
+billable attempt then fail at invocation. Codex absence/unusability never lowers a gate and never
+breaks a run — this is the portability promise. "Eligible" in this file means USABLE.
+
+**Cost gate (F-D).** Codex calls are billable (external GPT-5.x). Fire them ONLY at high-value
+moments: a two-strikes deadlock, a security-class card review, or an explicit operator opt-in.
+Never call Codex on every stage by default.
+
+## Antigravity — the cross-vendor third engine (Gemini-3)
+
+When `agy` (CLI) or the Antigravity IDE is present, a **fifth path** unlocks: **Antigravity
+(Google Gemini-3)** — a third vendor's model, sibling to Codex. Used at the same three high-value
+moments (two-strikes after Codex, security-class review, operator opt-in) to give a genuine
+**three-model** adversarial gate. Full seam (invocation, shapes, cost/data gate): **`references/antigravity-integration.md`**.
+
+**Detection — installed ≠ usable, and NEVER route on exit code.** Antigravity needs the strictest
+usability check: `agy -p` returns **exit 0 with empty stdout even when unauthenticated** (the error
+only lands in `--log-file`; non-TTY capture is empty). So **only non-empty expected output proves
+USABLE** — never exit code, never empty stdout. INSTALLED = `agy`/IDE/`~/.gemini` present; USABLE =
+INSTALLED + a liveness probe returns a non-empty sentinel token. Not usable (unauthenticated, or
+non-TTY capture empty — common in headless/CI and piped agent harnesses) or absent → **degrade** to
+Codex / ck:→bmad→built-in, announce "antigravity tier unavailable — degraded to <path>", record the
+reason. Because headless capture is unreliable, the **supported default is interactive** (IDE Agent
+Manager / real `agy` terminal, paste the ReviewResult back); an empty Gemini result is
+"review-unavailable", **never** an approval. Same billable + data-leaves-machine cost gate as Codex.
+
+## Rules
+
+- **Same gate regardless of path.** The buildflow gate (`flow.sh` + `gate-rules.md`) is the
+  contract. An agent fills an artifact; the gate still judges it. A missing agent never
+  lowers a gate — it only changes who drafts.
+- **Context isolation (orchestration-protocol).** Give each subagent ONLY: the task, the
+  specific files to read/modify, acceptance criteria, and relevant law/contract excerpts.
+  Never the full session history. One card = one scoped brief.
+- **Status protocol.** Every subagent returns DONE / DONE_WITH_CONCERNS / BLOCKED /
+  NEEDS_CONTEXT. Handle BLOCKED/NEEDS_CONTEXT before retry (more context → simpler task →
+  escalate). Two-strikes: a second red result → **Codex rescue if the tier is eligible**
+  (`codex:codex-rescue`, a different engine), else fresh subagent, else escalate to operator.
+- **Durable record hook.** After a stage/card agent finishes, write the durable record via
+  `flow.sh harness ...` (story add/update, trace, decision add) so progress survives the
+  session. See `agent-stage-mapping.md` for the per-stage hook.
+- **Announce the path.** Tell the operator which path ran ("research via `researcher`
+  agent" / "via bmad-market-research" / "inline fallback") so the run is legible.

package/skills/flow/references/agent-stage-mapping.md

@@ -0,0 +1,114 @@
+# Stage -> agent mapping
+
+How each buildflow stage delegates to a specialist. Pick the path by `agent-detection.md`
+priority (ck: first, bmad alternative, built-in fallback). The artifact + gate are
+identical across paths; only the drafter changes.
+
+**Codex (cross-vendor second engine) column.** When the codex tier is eligible
+(`agent-detection.md` / `codex-integration.md`), each stage gains two extra options on top of the
+ladder below: (1) **rescue** — if the chosen path is BLOCKED twice, hand the scoped brief to
+`codex:codex-rescue` before escalating; (2) **opt-in primary** — the operator may select Codex as
+the primary drafter for **research** and **build** stages (`codex:codex-rescue --write` /
+`codex-companion.mjs task --write`). **Default stays ck:**; Codex-as-primary is operator-selected,
+never automatic. The scope/PRD/ADR/Contract judgment stages stay Claude by default (Codex may
+still rescue them). The stage gate is identical on the Codex path — Codex drafts, the gate judges. In `teach` mode you do NOT author — you
+gatekeep; agents assist the operator. In `work`/`auto` mode you (or the agent) draft, then
+the gate still judges.
+
+Artifact language: **Vietnamese for user-facing copy** (per `law/DESIGN.md`: VN native,
+`₫` prices, VietQR), **English for code identifiers/endpoints**.
+
+## Brownfield pre-stage (existing codebase)
+
+If the project ALREADY EXISTS, run `/flow assess` first → `flow/00-inspect.md` (current-state map:
+stack, functionality/UI/UX vs product goals, risks, test baseline). Delegate to `ck:scout` +
+`researcher` (or `bmad-document-project`); the gate is operator-reviewed. This seeds planning (and
+the harness) with reality before stage 01. Greenfield projects skip it and start at `/flow next` (00).
+
+## Planning stages (flow/)
+
+| Stage | ck: (primary) | bmad (alt) | fallback | Durable hook |
+|---|---|---|---|---|
+| 01 Research | `researcher` | `bmad-market-research` / `bmad-technical-research` | `Explore` + WebSearch | `harness intake --type new_spec` |
+| 02 Scope | `planner` | `bmad-prd` (scope) | inline | record scope decision |
+| 03 PRD | `planner` | `bmad-prd` / `bmad-product-brief` | inline | — |
+| 04 ADR | `architect` | `bmad-create-architecture` | inline | `harness decision add` per ADR |
+| 05 Contract | `planner` | `bmad-spec` (5-field kernel) | inline | — |
+
+**Optional ck-skill enrichments per stage** (the skill layer on top of the agents above; the
+agent drafts, a skill adds a distinct verb): the curated whitelist + the rules (skill INFORMS,
+gate JUDGES; Claude-side detection; opt-in-with-prompt) live in **`references/claudekit-skills.md`**.
+Deep-wired into the gate ritual (all opt-in-with-prompt, degrade silently, never auto-pass a
+gate): **`ck-predict` at ADR** (5-persona pre-decision debate) and **`ck-scenario` at Contract**
+(12-dim edge-case → acceptance + contract tests) — both in `gate-rules.md`; **`review-pr` +
+`ck-security` at the Review gate** (PR-context lens / STRIDE+OWASP on security-class cards) — in
+`adversarial-review.md`; **`retro` at Retro** (git-history numbers for the operator's line) — in
+`law/RETRO.md`. After any of these runs at its gate, record the lazy durable metric
+(`flow.sh harness intervention add`). Full whitelist + rules: `references/claudekit-skills.md`.
+
+## Shipping (inside cards/)
+
+| Step | ck: (primary) | bmad (alt) | fallback | Durable hook |
+|---|---|---|---|---|
+| Build card | `fullstack-developer` | `bmad-dev-story` / `bmad-quick-dev` | inline | `harness story update --status in_progress` |
+| UI card | `ui-ux-designer` | — | inline + `law/DESIGN.md` | review vs DESIGN.md |
+| Repair / diagnostic | `debugger` | — | inline root-cause + fresh same-ladder subagent | `harness intervention add` |
+| Review | `code-reviewer` (+ `typescript-reviewer` or `python-reviewer` layered — see language-specialist lens) | `bmad-code-review` (3-layer adversarial) | inline | `harness intervention add` on red |
+| Deploy / git ship | `git-manager` | — | inline commit + PR guide | `harness story update --status implemented` |
+| Docs sync | `docs-manager` | — | inline doc update | — |
+| Verify-live | `tester` / `web-testing` | `bmad-qa-generate-e2e-tests` | curl/Playwright | `harness story update --e2e 1` + `trace` |
+
+**Portability degrade rungs for git-manager and docs-manager:**
+- `git-manager` absent → inline: operator runs `git commit` + `git push` + opens PR manually following the durable-hook pattern. Gate (PR merged, SHA logged in `AUTO-LOG.md`) is identical.
+- `docs-manager` absent → inline: Claude updates docs directly after card implementation; gate (impacted docs under `docs/` match the code change) is identical.
+
+**Portability degrade rungs for the language-specialist Review lens** (`adversarial-review.md` §Language-specialist lens selection):
+- `typescript-reviewer` or `python-reviewer` AGENT present → run it layered with `code-reviewer` for `.ts/.tsx/.js/.jsx` or `.py` cards respectively. Gate (triage table, adversarial verdict) is identical.
+- Specialist absent → `code-reviewer` runs an explicit language-targeted checklist (TypeScript: `any` escapes, unhandled promises, strict mode; Python: bare `except`, missing type hints, mutable defaults). Gate is identical.
+- No dominant language → `code-reviewer` only; no specialist layer. Gate is identical.
+
+## Scoped prompt template (use for EVERY delegation)
+
+Keep it small. No session history. Fill every slot from the live artifacts.
+
+```
+Task: <one stage/card goal>
+Read for context: flow/05-contract.md (shapes), law/DESIGN.md (UI only),
+  flow/03-prd.md (features), the card file <path>, playbooks/<stack>.md if the stack matches
+Files to modify: <card ## Allowed files ONLY>
+Acceptance criteria: <the stage gate from gate-rules.md, or the card ## Verify steps>
+Constraints: contract is the seam (never improvise a shape); done = world-state evidence;
+  Vietnamese user-facing copy; touch only allowed files
+Return: the drafted artifact + status (DONE/DONE_WITH_CONCERNS/BLOCKED/NEEDS_CONTEXT)
+```
+
+## Stage notes
+
+- **05 Contract via bmad-spec:** the 5-field spec kernel (Why, Capabilities, Constraints,
+  Non-goals, Success signal) maps onto the contract — Capabilities -> endpoints, Constraints
+  -> auth/shape rules. Use it to harden the seam against producer/consumer drift. The
+  endpoint table in `flow/05-contract.md` remains the runtime-checkable source of truth.
+- **Review via bmad-code-review (3-layer):** when present, prefer it for card review — Blind
+  Hunter (diff only), Edge Case Hunter (diff + repo), Acceptance Auditor (diff + contract +
+  PRD). "Must find issues; zero findings -> re-analyze." This is the adversarial gate
+  detailed in `adversarial-review.md` (Phase 4).
+- **Build via fullstack-developer:** one card = one scoped session. Pass the card's Scope +
+  Allowed files + the contract shapes it consumes. It must honor shapes exactly.
+- **Repair / diagnostic via debugger:** detect-first ladder entry — NOT a hard dependency.
+  Dispatch `Task(subagent_type="debugger")` with a scoped brief: task description, the failing
+  card file, test output, and `## Verify` acceptance criteria. NO session history (context
+  isolation per orchestration-protocol). If `debugger` is ABSENT in the host, degrade to inline
+  root-cause analysis + a fresh same-ladder (Claude) subagent for the redraw. A missing agent
+  changes WHO diagnoses, never whether `## Verify` + `flow.sh check` must pass for real.
+  Escalation order: debugger (Claude diagnostic) -> Codex (if USABLE) -> Antigravity (if USABLE)
+  -> operator.
+- **Verify-live:** the proof is the LIVE surface (deployed URL, real curl), not "tests pass".
+  Record `story update --e2e 1` + a `trace` only after the live check.
+
+## After any delegation
+1. Run the gate (`flow.sh next` for stages, `flow.sh check C-NNN` for cards).
+2. Apply the semantic challenge from `gate-rules.md`.
+3. Write the durable hook above. NOTE: the engine now AUTO-fires some — `flow next` past 01 seeds
+   `intake`, past 04 reminds `decision add`; `flow check` (done) records the `trace` and shows its
+   tier. You still author the content the engine can't (decision rationale, interventions, rich traces).
+4. Announce which path ran + the gate verdict to the operator.

package/skills/flow/references/antigravity-integration.md

@@ -0,0 +1,92 @@
+# Antigravity — cross-vendor third engine (the seam)
+
+`/flow` reaches Google **Antigravity (Gemini-3)** through the `agy` CLI and/or the Antigravity IDE
+(detected, never required). Antigravity is a *third engine* alongside the ck:→bmad→built-in ladder
+and the Codex (GPT-5.x) second engine — a genuinely different vendor's model used where a third
+independent perspective is worth more than another Claude or Codex pass. This file is the single
+source of truth for the seam; `agent-detection.md` (detection + priority) and `adversarial-review.md`
+(cross-model review) point here for the shapes. It mirrors `codex-integration.md`; read that first.
+
+## Why a third vendor
+
+Cross-model review empirically catches more than single-model (a gemini-cli study: 43% vs 91%
+merge-ready). flow already crosses Claude × Codex; adding Gemini-3 gives a **three-model** adversarial
+gate — three vendors rarely share the same blind spot. Antigravity also runs natively as the
+operator's daily IDE/CLI, so flow installed there is a portability win even before any review use.
+
+## Detection — two states: INSTALLED vs USABLE (never route on "installed", and NEVER on exit code)
+
+Antigravity needs the **strictest** usability check of any tier, because of a measured platform fact:
+
+> **The `agy` exit code lies.** `agy -p "<prompt>"` returns **exit 0 with empty stdout** even when it
+> is unauthenticated ("You are not logged into Antigravity") — the error surfaces only in
+> `--log-file`. Non-TTY stdout capture is also empty (raw pipe and `winpty` both yield nothing on
+> Windows Git Bash). Verified 2026-06-16. So exit code 0 means **nothing** here; only **non-empty,
+> expected output** proves usability.
+
+- **INSTALLED** — `agy` is on `PATH` (or `~/AppData/Local/agy/bin/agy`), or the IDE
+  (`~/AppData/Local/Programs/Antigravity`), or `~/.gemini/` exists. Necessary, not sufficient.
+- **USABLE** — INSTALLED **and** a liveness probe returns a **non-empty response containing an
+  expected sentinel token** (e.g. ask `agy -p` to echo `FLOWPONG` and require that token in stdout).
+  **Never** treat exit 0 as success; **never** treat empty stdout as success. If the probe is empty
+  or the log shows "not logged into Antigravity" → state = NOT USABLE.
+
+**Selection rule:** only select the Antigravity tier when state = **USABLE**. INSTALLED-but-not-USABLE
+(unauthenticated, or non-TTY capture returns empty — common in headless/CI and in agent harnesses
+that pipe stdout) or absent → **degrade** to Codex / ck:→bmad→built-in, announce
+`"antigravity tier unavailable (installed but not authenticated / no capturable output) — degraded
+to <path>"`, record the reason. Degrading is silent-but-announced, never an error, never a gate change.
+
+## Headless capture is unreliable → interactive is the supported default
+
+Because non-TTY `agy -p` capture is empty on this platform, the **supported** way to run a Gemini-3
+cross-model review is **interactive**: the operator runs the review in the Antigravity IDE (Agent
+Manager) or a real `agy` terminal and pastes the `ReviewResult` back to flow. The **headless** path
+(`agy -p` from flow's runner) is offered ONLY behind a passing liveness probe; if the probe is empty,
+flow must NOT fall back to "no findings = pass" — an empty Gemini result is **"review unavailable"**,
+never an approval. This is the loud-degrade rule applied to a vendor whose exit code can't be trusted.
+
+## Cost / data gate — when the Antigravity tier is allowed to fire
+
+Gemini-3 calls are **billable** external inference and **send the diff + specs to Google's API**
+(governed by the operator's Google/Gemini plan and its retention/training terms). Fire ONLY at
+high-value moments, same closed set as Codex:
+- a **two-strikes deadlock** (after Codex, if both a same-model and the second engine stall),
+- a **security-class card review** (auth/authorization/tenancy/payments/data-migration), or
+- an **explicit operator opt-in** (e.g. "review this on Antigravity", "/flow ... antigravity").
+
+Never call Antigravity on every stage by default. Default engine stays ck:; second engine stays Codex.
+For a sensitive/regulated/NDA'd codebase the operator must opt in knowingly — the code and specs leave
+the machine to a third vendor.
+
+## Invocation surfaces (do not improvise other shapes)
+
+| Use | Invocation | Notes |
+|---|---|---|
+| **Liveness probe (USABLE check)** | `agy -p "echo token FLOWPONG" --print-timeout 30s` | require `FLOWPONG` in non-empty stdout; exit code is ignored (it lies) |
+| **Interactive review (supported default)** | operator runs Antigravity IDE Agent Manager / real `agy` terminal, pastes back `ReviewResult` | the only path not blocked by non-TTY capture |
+| **Headless review (gated on liveness)** | `agy -p "<review brief>" --log-file <f> --print-timeout <t>` | only if liveness passed; require non-empty output; empty = review-unavailable, NEVER a pass |
+| **Skill install homes** | flow's installer deploys to CLI `~/.gemini/antigravity-cli/skills/flow` + IDE `~/.gemini/config/skills/flow`. Antigravity also recognizes shared `~/.gemini/skills/` and project `<root>/.agents/skills/flow`, but the installer does NOT write those (use them only for a manual/project copy). | same `SKILL.md` bundle Antigravity reads (no restructuring) |
+
+`agy inspect` lists the config + skills Antigravity has loaded — use it to confirm flow is discovered.
+
+### ScopedBrief / ReviewResult / Status protocol
+Identical to `codex-integration.md`: give the engine ONLY task · read-for-context · files-to-modify ·
+acceptance · constraints · return (never session history). Review output is coerced to the same
+`ReviewResult` shape (verdict / summary / findings[] / next_steps). Handoffs return
+`DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT`.
+
+## Gate parity (absolute) & auth (delegated)
+
+- **Gate parity.** Antigravity DRAFTS or CRITIQUES; the identical stage gate (`flow.sh` +
+  `gate-rules.md`) still judges. A Gemini-3 review INFORMS triage — it never auto-passes or
+  auto-fails a card.
+- **Auth.** Delegated entirely to `agy`/the IDE (interactive `agy` login). `/flow` never reads,
+  stores, or logs Antigravity credentials. An unauthenticated `agy` is NOT USABLE (see detection).
+
+## Durable metric & announce
+
+After an Antigravity tier use, log it (`flow.sh harness intervention add` / `decision add`) so the
+quality loop can read the three-model-catch trend. Always announce which engine ran:
+`"review via Antigravity (Gemini-3) cross-model lens (needs-attention, 2 findings)"` /
+`"antigravity tier unavailable (not authenticated) — degraded to Codex"`. A run stays legible.

package/skills/flow/references/auto-run.md

@@ -0,0 +1,81 @@
+# /flow auto — autonomous build run
+
+`/flow auto` drives the card-building phase autonomously. Preflight via
+`flow.sh auto` (planning complete + cards exist), then YOU (Claude) orchestrate per the
+principles below. Operator chose: **Tier-A auto-merge green cards; halt at security-class.**
+
+## Tiers (decide per card before acting)
+
+| Tier | What | Action |
+|---|---|---|
+| **A** | Card built, review green, verify-live passed, no security-class concern | **Auto-merge without asking.** Log PR URL + merged SHA in `AUTO-LOG.md`. |
+| **B** | Built but review found fixable issues, or verify ambiguous | First repair = **`Task(subagent_type="debugger")`** with scoped brief (task + card + test output + acceptance; no session history). If `debugger` is absent, degrade to inline root-cause + fresh same-ladder (Claude) subagent. If THAT repair is still red — the **two-strikes deadlock** — THEN try the next USABLE cross-vendor engine: **Codex** (`codex:codex-rescue`) first, then **Antigravity/Gemini-3** (`antigravity-integration.md`) if Codex is unusable or also red; else escalate to operator. (A cross-vendor engine may come in earlier ONLY on a security-class card or explicit operator opt-in — the cost gate. Do NOT call a billable engine on the first red of an ordinary card.) |
+| **C** | Security-class touch (auth, authorization, admin exposure, tenancy, payments, data migration, removing validation) OR a debt skip | **HALT.** Operator must accept the exposure in writing in `DEBT.md`. Never planner-decided. |
+
+## Loop per card (serial by default; parallel only when `/flow ready` says safe)
+
+```
+for each todo card in card-number order:
+  0. tier-classify. If Tier-C -> HALT, write DEBT line, ask operator. Do not proceed.
+  1. spawn ONE scoped subagent (agent-stage-mapping.md) in its own worktree
+     git worktree add ../<project>-C-NNN -b card/C-NNN
+  2. agent builds to contract, touches only allowed files, runs ## Verify for real
+  3. review the diff (code-reviewer or bmad-code-review 3-layer; see adversarial-review.md).
+       On a security-class card, add a USABLE cross-vendor lens (Codex, and/or Antigravity/Gemini-3).
+       red (strike 1) -> repair: spawn Task(subagent_type="debugger") with a SCOPED BRIEF
+         (task + failing card file + test output + ## Verify acceptance; NO session history).
+         Debugger diagnoses root cause and returns a fix recommendation or revised implementation.
+         Degrade rung: if `debugger` is ABSENT in the host, run inline root-cause analysis then
+         spawn a FRESH same-ladder (Claude) subagent for the redraw. A missing `debugger` changes
+         WHO diagnoses, never whether ## Verify + flow.sh check must pass for real.
+       still red (strike 2 / deadlock) -> Codex fresh-engine repair if USABLE, then Antigravity if
+         USABLE, else escalate
+       green -> continue
+  4. flow.sh check C-NNN must PASS (mechanical) + gate-rules semantic check
+  5. merge to main in card order; deploy; VERIFY ON LIVE URL (merge != shipped)
+  6. paste world-state evidence into the card; status: done
+  7. flow.sh harness story update --status implemented + trace; log AUTO-LOG.md
+  8. remove worktree
+```
+
+## Hard stops (mandatory — see loop-harness-2026-principles.md in Phase 4)
+- Iteration cap per card (e.g. 2 repair attempts), token budget, wall-clock cap. Exceed any
+  -> HALT + report. A loop with no cap is an antipattern.
+- Ground-truth gates only at decision points: `flow.sh` exit, `## Verify` real runs, story
+  `verify_command`, deploy + live check. Never advance on an agent's self-assessment alone.
+
+## Repair discipline — full-suite re-run required
+A control-flow / runner repair (any change to `flow.sh`, `run_all.sh`, a test helper, or any
+shared test fixture) MUST re-run the FULL suite (`bash tests/run_all.sh`) before claiming
+green — not just the targeted suite that triggered the repair. A repair subagent that ran
+**only the targeted suite** is **BLOCKED**, not done. Rationale: runner-layer changes can break
+suites that were not failing before the repair (the C-015 regression was caught only by the
+full run, not by the targeted re-run).
+
+## AUTO-LOG.md schema (one line per card)
+```
+- C-NNN | <title> | tier=A | review=green | PR=<url> | merged=<sha> | live=<verified-url> | <date>
+- C-NNN | <title> | tier=C HALT | reason=<security-class> | DEBT opened | <date>
+- C-NNN | <title> | tier=B | repair=codex:codex-rescue | result=green | PR=<url> | <date>
+```
+When a Codex engine drafted/repaired/reviewed a card, name it in the line (`repair=` / `review=`)
+and log the durable metric (`flow.sh harness intervention add`) per `codex-integration.md` §Durable metric.
+
+## Parallel groups
+`/flow ready` lists todo cards with deps met AND no allowed-files overlap. Only those run in
+parallel, each in its own worktree/session. Merge back in card-number order, one at a time,
+running the merged app once between merges. A merge conflict means the overlap check was
+gamed — stop and re-plan. Cards needing the deployed app (contract-tests, e2e) are serial.
+
+**Human-driven `/flow workspace` coexists with this auto loop.** `auto` provisions a worktree per
+card internally (`git worktree add ../<project>-C-NNN -b card/C-NNN`); `/flow workspace add card/C-NNN`
+uses the *same* `card/C-NNN` branch naming, so if a human and an `auto` run ever target one card,
+git's own "a branch can only be checked out in one worktree" refusal is the guard — the second
+`add` fails verbatim rather than double-creating. Run `/flow workspace doctor` after an `auto` run
+to reconcile any worktree it left as an orphan tree (no side-file record).
+
+## Security-class halt (never silent, never planner-decided)
+auth · authorization · admin-surface exposure · tenancy · payments · data loss/migration ·
+removing/weakening validation. On any: stop, write the `DEBT.md` line with the concrete
+exposure + close condition, and get explicit operator acknowledgment before continuing.
+Closing a run with open security debt requires the operator to acknowledge it in writing.