@manhquy/flow-skill 0.7.4 → 0.7.5

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to `@manhquy/flow-skill`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
 
 
+## [0.7.5] — 2026-10-12 — ships skill v0.34.0 (stable / latest)
+
+Feature and stability release. Ships skill product **v0.34.0** with PIN v1 status/resume contract, runner concurrency lock guard, C1–C7 runner wave integrity checks, theme-aware brand headers, and cross-platform CI hardening. Installer CLI contract unchanged. Publishes to dist-tag **`latest`**.
+
+### Added
+- **Skill product v0.34.0:**
+  - PIN v1 status/resume contract: exact STOP body excerpts reprinted after `NEXT_VERB` on status/resume so compact hosts recover `FLOW_FORCE`, `HALT`, and hollow-done rules (`pin-v1.txt`).
+  - AgentKit (`ak:*`) aliases mapped across references.
+  - C5 runner integrity check: pack-time SHA-256 in `portable-manifest.json` and bundled `manifest-hashes.json` receipt, verified via `flow doctor`.
+- Theme-aware brand header lockups across docs and wrappers.
+
+### Fixed
+- **Runner concurrency lock:** Atomic `set -C` lock claim guard in `flow.sh` and `attestations.sh` to prevent `mkdir` race condition (#22).
+- **Cross-platform CI hardening:** Normalized harness `_db.py` path for Windows MSYS, fixed i18n CRLF test handling on Windows Git, and expanded Windows CI bash-suite timeout to 60m.
+
+### Changed
+- Bundled skill tree re-synced from monorepo `skills/flow/`.
+- Install: **`npx @manhquy/flow-skill@latest`**.
+
 ## [0.7.4] — 2026-10-11 — ships skill v0.33.0 (stable / latest)
 
 Documentation and brand release. Adds theme-aware gate-mark brand header to npm-wrapper READMEs (English and Vietnamese). Ships skill product **v0.33.0**. Installer CLI contract unchanged. Publishes to dist-tag **`latest`**.

package/README.md

@@ -12,7 +12,7 @@ Install the **flow** skill into coding agents with one command.
 | | |
 |---|---|
 | **Package** | [`@manhquy/flow-skill`](https://www.npmjs.com/package/@manhquy/flow-skill) (installer CLI) |
-| **Current GA** | **0.7.4** — ships skill product **v0.33.0** |
+| **Current GA** | **0.7.5** — ships skill product **v0.34.0** |
 | **Platforms** | macOS · Linux · Windows (same Node path) |
 | **Requirement** | Node.js **≥ 22.14** |
 | **Source** | [github.com/manhquydev/flow-skill](https://github.com/manhquydev/flow-skill) |
@@ -42,7 +42,7 @@ npx @manhquy/flow-skill@latest
 
 ```bash
 npx @manhquy/flow-skill@latest --help
-# expect: flow-skill v0.7.x (ships skill v0.33.x)
+# expect: flow-skill v0.7.x (ships skill v0.34.x)
 ```
 
 ### Common commands
@@ -97,7 +97,7 @@ npx @manhquy/flow-skill@latest --yes --all --dry-run --json
 |----|--------|
 | `npx @manhquy/flow-skill@latest` | Bare `npx @manhquy/flow-skill` (stale npx cache) |
 | **Run** the CLI to copy the skill | `npm i` alone (package only; no skill files in agent homes) |
-| Pin installer `@0.7.4` if needed | Pin npm `@0.33.0` (skill version ≠ package version) |
+| Pin installer `@0.7.5` if needed | Pin npm `@0.34.0` (skill version ≠ package version) |
 | Prefer `@latest` | `@rc` (retired / behind) |
 
 **Two version axes:** `package.json` version = installer; `SKILL.md` metadata = skill product. Both appear in `--help` and in the `plan` JSONL event (`version` + `skillVersion`).
@@ -145,7 +145,7 @@ rm -rf <project>/.claude/skills/flow
 |---------|-----|
 | Agent has no `/flow` after `npm i` | Run `npx @manhquy/flow-skill@latest` (install must **execute**) |
 | Old skill after reinstall | Always use `@latest`; avoid bare package name |
-| `No matching version found` for `@0.33.0` | That is the **skill** version. Use `@latest` or `@0.7.x` |
+| `No matching version found` for `@0.34.0` | That is the **skill** version. Use `@latest` or `@0.7.x` |
 | Node too old | Install Node ≥ 22.14 (`nvm install 22`, etc.) |
 | Windows `EBUSY` / `EPERM` | Close the agent holding files under the skill dir; re-run |
 | Stale install lock | Delete `<parent>/.flow-skill.installing.lock` if reclaim fails |
@@ -155,7 +155,7 @@ rm -rf <project>/.claude/skills/flow
 ## JSONL (`--json`)
 
 ```jsonl
-{"event":"plan","version":"0.7.4","skillVersion":"0.33.0","dryRun":false,"scope":"global","targets":["claude"]}
+{"event":"plan","version":"0.7.5","skillVersion":"0.34.0","dryRun":false,"scope":"global","targets":["claude"]}
 {"event":"install:start","target":"claude","dests":["~/.claude/skills/flow"]}
 {"event":"install:done","target":"claude","dests":["~/.claude/skills/flow"],"result":"success","error":null,"warnings":[]}
 {"event":"summary","success":true,"total":1,"attempted":1,"installed":1,"failed":0,"skipped":0,"aborted":false}

package/README_VN.md

@@ -12,7 +12,7 @@ Cài skill **flow** vào coding agent bằng một lệnh.
 | | |
 |---|---|
 | **Package** | [`@manhquy/flow-skill`](https://www.npmjs.com/package/@manhquy/flow-skill) (installer CLI) |
-| **GA hiện tại** | **0.7.4** — ships skill product **v0.33.0** |
+| **GA hiện tại** | **0.7.5** — ships skill product **v0.34.0** |
 | **Nền tảng** | macOS · Linux · Windows (cùng code path Node) |
 | **Yêu cầu** | Node.js **≥ 22.14** |
 | **Source** | [github.com/manhquydev/flow-skill](https://github.com/manhquydev/flow-skill) |
@@ -42,7 +42,7 @@ npx @manhquy/flow-skill@latest
 
 ```bash
 npx @manhquy/flow-skill@latest --help
-# expect: flow-skill v0.7.x (ships skill v0.33.x)
+# expect: flow-skill v0.7.x (ships skill v0.34.x)
 ```
 
 ### Lệnh hay dùng
@@ -97,7 +97,7 @@ npx @manhquy/flow-skill@latest --yes --all --dry-run --json
 |-----|--------|
 | `npx @manhquy/flow-skill@latest` | Bare `npx @manhquy/flow-skill` (cache npx có thể cũ) |
 | **Chạy** CLI để copy skill | Chỉ `npm i` (chỉ thêm package; không cài skill vào agent home) |
-| Pin installer `@0.7.4` nếu cần cố định | Pin npm `@0.33.0` (version **skill** ≠ version package) |
+| Pin installer `@0.7.5` nếu cần cố định | Pin npm `@0.34.0` (version **skill** ≠ version package) |
 | Ưu tiên `@latest` / `@0.7.x` | `@rc` (đã retire / tụt hậu) |
 
 **Hai trục version:** `package.json` = installer CLI; `SKILL.md` metadata = skill product. Cả hai hiện trong `--help` và event JSONL `plan` (`version` + `skillVersion`).
@@ -145,7 +145,7 @@ rm -rf <project>/.claude/skills/flow
 |------------|------------|
 | Agent không có `/flow` sau `npm i` | Chạy `npx @manhquy/flow-skill@latest` (phải **execute** installer) |
 | Skill cũ sau khi “cài lại” | Luôn dùng `@latest`; tránh bare package name |
-| `No matching version found` với `@0.33.0` | Đó là version **skill**. Dùng `@latest` hoặc `@0.7.x` |
+| `No matching version found` với `@0.34.0` | Đó là version **skill**. Dùng `@latest` hoặc `@0.7.x` |
 | Node quá cũ | Cài Node ≥ 22.14 (`nvm install 22`, v.v.) |
 | Windows `EBUSY` / `EPERM` | Đóng agent đang giữ file trong skill dir; chạy lại |
 | Stale install lock | Xóa `<parent>/.flow-skill.installing.lock` nếu reclaim thất bại |
@@ -155,7 +155,7 @@ rm -rf <project>/.claude/skills/flow
 ## JSONL (`--json`)
 
 ```jsonl
-{"event":"plan","version":"0.7.4","skillVersion":"0.33.0","dryRun":false,"scope":"global","targets":["claude"]}
+{"event":"plan","version":"0.7.5","skillVersion":"0.34.0","dryRun":false,"scope":"global","targets":["claude"]}
 {"event":"install:start","target":"claude","dests":["~/.claude/skills/flow"]}
 {"event":"install:done","target":"claude","dests":["~/.claude/skills/flow"],"result":"success","error":null,"warnings":[]}
 {"event":"summary","success":true,"total":1,"attempted":1,"installed":1,"failed":0,"skipped":0,"aborted":false}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manhquy/flow-skill",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "Install the flow skill (buildflow gated build process) into your coding agent(s) via one npx command",
   "type": "module",
   "bin": {

package/skills/flow/SKILL.md

@@ -8,7 +8,7 @@ keywords: [flow, buildflow, gate, build, ship, scope, prd, contract, card, deplo
 license: MIT
 metadata:
   author: flow-skill
-  version: "0.33.0"
+  version: "0.34.0"
   attribution: "Methodology from ai20k-build-phase/buildflow (Tony, arealisticdreamer.com); durable-layer ancestry and improve-ritual spirit from repository-harness (protocol v1 EOL — flow-owned fork); agent patterns from claudekit-engineer, BMAD-METHOD. v0.22 concierge from BMAD bmad-help; forge-idea from bmad-forge-idea (MIT, BMad Code LLC)."
 ---
 
@@ -136,7 +136,7 @@ only when `bash` is Git Bash.
 - Codex second engine: `references/codex-integration.md`.
 - Antigravity Gemini-3 **third engine**: `references/antigravity-integration.md`
   (confirm load with `agy inspect`).
-- ck-skill layer: `references/claudekit-skills.md`.
+- ck/ak skill layer: `references/claudekit-skills.md`.
 - Parallel occupancy: `references/host-agnostic-parallel.md`.
 - Receipts: `references/attestations.md`.
 - `harness/` is **flow-owned**. Improve via **R-IMPROVE-HARNESS** in

package/skills/flow/manifest-hashes.json

@@ -1,3 +1,3 @@
 {
-  "skills/flow/runner/flow.sh": "c023283bd6c2ed103310eeee3a10211c27a5dd79cf0f8dccbd67fc89dcf66a67"
+  "skills/flow/runner/flow.sh": "2dcd25dadb2a8636a8065d6e974613949a3421cdf7b61d08a676427dbb07b390"
 }

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

@@ -20,13 +20,14 @@ STRIDE categories regardless of which lens above is present. Output INFORMS tria
 
 **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
+(or `ak:security` — same row, `claudekit-skills.md` Name resolution) 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.
 
-**If `ck-security` is installed**, offer it as a richer alternative / extra threat-model
+**If `ck-security` is installed** (or `ak:security`), offer it as a richer alternative / extra threat-model
 pass on top of the native ritual (opt-in-with-prompt) — the operator confirms; it is not
-auto-fired. Same INFORMS-only rule. After either the native ritual or `ck-security` runs,
-record the lazy durable metric via `flow.sh harness intervention add` (the wired-gate
+auto-fired. Same INFORMS-only rule. After either the native ritual or `ck-security` /
+`ak:security` 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):
@@ -161,7 +162,7 @@ Same parity rule: it INFORMS, never auto-passes/auto-fails. Log the same durable
 ## 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
+**GitHub PR**, offer the `review-pr` SKILL (or `ak:review-pr` — same row) 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`.

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

@@ -8,14 +8,18 @@ unbroken where they don't.
 
 The host's inline/generic path is always available. Overlay named specialists only when the
 host registry actually lists them — do not assume a Task tool, ck: agents, or any one vendor.
-Detect by checking that registry. Also glob for project-local definitions when unsure:
-- ck: agents: `.claude/agents/*.md` (project) and the host agent registry.
+Detect by checking that registry. Specialist names may be **unprefixed** (e.g. `architect`),
+**ck-prefixed** (`ck:architect` / `ck-architect`), or the same token under another kit.
+Strip `ck:` / `ck-` / `ak:` / `ak-` before comparing. Also glob for project-local
+definitions when unsure:
+- specialists: `.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)
+## Priority order (host specialist 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.
+1. **Host specialist** (primary) — planner, researcher, architect, fullstack-developer, code-reviewer, typescript-reviewer, python-reviewer, tester, ui-ux-designer, docs-manager, git-manager, debugger, scout.
+Specialists may be unprefixed or `ck:`/`ck-`/`ak:` spelled. This is the Codex / Cursor / Claude Code / AgentKit roster.
 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** — the host drafts inline, or spawns a generic `Explore`/`general-purpose` agent. Output shape must match the agent path so the gate is identical.
 

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

@@ -1,7 +1,7 @@
 # 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
+priority (host-native / 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
@@ -9,9 +9,11 @@ identical across paths; only the drafter changes.
 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 the host does NOT author — it
+`codex-companion.mjs task --write`). **Default stays ck: / host specialist**
+(`planner` / `ck:planner`); Codex-as-primary is operator-selected,
+never automatic. The scope/PRD/ADR/Contract judgment stages stay the host by default (Codex may
+still rescue them). The stage gate is identical on the Codex path — Codex drafts, the gate judges.
+In `teach` mode the host does NOT author — it
 gatekeeps; agents assist the operator. In `work`/`auto` mode the host (or a specialist) drafts, then
 the gate still judges.
 
@@ -21,8 +23,8 @@ Artifact language: **English for code identifiers/endpoints**. User-facing copy
 ## 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
+stack, functionality/UI/UX vs product goals, risks, test baseline). Delegate to `scout` /
+`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/)
@@ -35,16 +37,16 @@ the harness) with reality before stage 01. Greenfield projects skip it and start
 | 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
+**Optional 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`**.
+gate JUDGES; host-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
+gate): **`ck-predict` at ADR** (or `ak:predict` — 5-persona pre-decision debate) and **`ck-scenario` at Contract**
+(or `ak:scenario` — 12-dim edge-case → acceptance + contract tests) — both in `gate-rules.md`; **`review-pr` +
+`ck-security` at the Review gate** (`ak:review-pr` / `ak:security`; 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`.
+(`flow.sh harness intervention add`). Full whitelist + Name resolution: `references/claudekit-skills.md`.
 
 ## Shipping (inside cards/)
 

package/skills/flow/references/claudekit-skills.md

@@ -1,12 +1,13 @@
 # claudekit skills — the per-stage capability map (the seam)
 
-`/flow` already orchestrates claudekit at the **agent layer** (`agent-detection.md` +
-`agent-stage-mapping.md`: 13 ck: agents, ck:→bmad→built-in degrade). This file extends that
-same seam to the **skill layer** — the curated set of ck *skills* worth reaching for at each
-stage, beyond the wired agents. It is a **whitelist, not a dump**: the kit has ~87 skills and
-~60% are marketing/content noise for a build harness. Only the skills below ever get surfaced.
-
-This is the single source of truth for the skill map; `agent-stage-mapping.md` points here.
+`/flow` already orchestrates specialists at the **agent layer** (`agent-detection.md` +
+`agent-stage-mapping.md`: host-native / ck: agents, then bmad, then built-in). This file
+extends that same seam to the **skill layer** — the curated set of build skills worth
+reaching for at each stage. It is a **whitelist, not a dump**: ClaudeKit (~87) and
+AgentKit (~100+) both ship marketing/content noise. Only the skills below ever get
+surfaced. ClaudeKit `ck-*` and AgentKit `ak:*` names are the **same rows** (Name
+resolution). This is the single source of truth for the skill map;
+`agent-stage-mapping.md` points here.
 
 ## Standalone note (v0.22)
 
@@ -32,6 +33,33 @@ review natively.
    missing skill **never lowers a gate** — it only changes whether the enrichment is offered.
    Rich where the skill exists, unbroken where it doesn't.
 
+
+## Name resolution (ClaudeKit + AgentKit)
+
+Host registries spell the same skill three ways: `ck-<slug>`, `ak:<slug>` /
+`ak-<slug>`, or bare `<slug>`. Strip `ck:` / `ck-` / `ak:` / `ak-` and match the
+slug. Offer the **first listed** alias; never offer two names for one verb.
+AgentKit is not a dependency — absence degrades to the native ritual.
+
+| Whitelist row | Also detect |
+|---|---|
+| ck-predict | ak:predict, ak-predict, predict |
+| ck-scenario | ak:scenario, ak-scenario, scenario |
+| ck-security | ak:security, ak-security |
+| ck-loop | ak:loop, ak-loop, loop |
+| ck-graphify | ak:graphify, ak-graphify, graphify |
+| review-pr | ak:review-pr, ak-review-pr |
+| security-scan | ak:security-scan, ak-security-scan |
+| retro | ak:retro, ak-retro |
+| xia | ak:xia, ak-xia |
+| deploy | ak:deploy, ak-deploy |
+| web-testing | ak:web-testing, ak-web-testing |
+| docs-seeker | ak:docs-seeker, ak-docs-seeker |
+| scout | ak:scout, ak-scout |
+| repomix | ak:repomix, ak-repomix |
+
+`gkg` / `ak:gkg` stay unwired (single graph pick = ck-graphify / ak:graphify).
+
 ## Cost gate — offer, don't impose
 
 The high-value skills below are **opt-in-with-prompt**: at the matching gate you *offer* the
@@ -91,10 +119,10 @@ tail, plumbing via `flow.sh loop-prep`/`loop-log` (this file).
 6. **ck-loop @ Build/Verify (Implement→Test→Audit→Fix tail)** — when a fix needs more than one
    experimental attempt against a single numeric target (failing-test count, lint errors, etc.),
    offer `flow.sh loop-prep <card>` to set up an isolated worktree + Verify/Guard commands, then
-   invoke the `ck-loop` skill with the printed block (ck-loop stays the untouched execution
-   engine — flow supplies plumbing only). See "Loop vs two-strikes" below for when to reach for
-   this instead of the default repair path. The finished run is recorded via `flow.sh loop-log`
-   (NOT the `intervention` channel below — recording it twice would double-count the same event).
+   invoke `ck-loop` or `ak:loop` with the printed block (the loop skill stays the untouched
+   execution engine — flow supplies plumbing only). See "Loop vs two-strikes" below. The
+   finished run is recorded via `flow.sh loop-log` (NOT the `intervention` channel below —
+   recording it twice would double-count the same event).
 
 ## Loop vs two-strikes — the one "fix it" decision tree
 
@@ -105,20 +133,22 @@ different tool for a different situation; do not let operators reach for the wro
 | Situation | Use | Why |
 |---|---|---|
 | Review BLOCKED twice, same model, no metric | two-strikes → cross-model lens | bounded disagreement, not a number |
-| One numeric verify command, needs >1 experimental attempt | `flow.sh loop-prep` + ck-loop | open iterate-to-target, git-tracked/revertable |
-| Drive failing-tests / lint / perf count to a threshold | ck-loop | Verify is a single number; Direction lower |
+| One numeric verify command, needs >1 experimental attempt | `flow.sh loop-prep` + ck-loop / ak:loop | open iterate-to-target, git-tracked/revertable |
+| Drive failing-tests / lint / perf count to a threshold | ck-loop / ak:loop | Verify is a single number; Direction lower |
 | Single obvious fix, one retry | default auto repair | cheaper than spinning up a worktree+loop |
 
 ## Don't surface (cut on purpose — these add noise, not signal)
 
 - **Skill/agent twins** — the wired agent already covers these; surfacing the duplicate skill
-  doubles the "what do I use" confusion: research/researcher, ck-code-review/code-reviewer,
-  ck-debug/debugger, test/tester, git/git-manager, ck-plan/planner, docs/docs-manager,
-  journal/journal-writer, ask, brainstorm. Prefer the **agent** for in-stage execution; reach
-  for the skill only for a distinct verb the agent lacks (already captured above).
-- **Competing orchestrators (cook, vibe, ship, bootstrap)** — each is its own end-to-end
+  doubles the "what do I use" confusion: research/researcher, ck-code-review / ak:code-review /
+  code-reviewer, ck-debug / ak:debug / debugger, test / ak:test / tester, git / ak:git /
+  git-manager, ck-plan / ak:plan / planner, docs / ak:docs / docs-manager, journal /
+  ak:journal / journal-writer, ask, brainstorm. Prefer the **agent** for in-stage execution;
+  reach for the skill only for a distinct verb the agent lacks (already captured above).
+- **Competing orchestrators (cook, vibe, ship, bootstrap, agentkit, plan, orchestrate, team, handover, issue-to-plan, fix)** — each is its own end-to-end
   pipeline with its own gates; invoking one inside a flow stage double-gates and fights flow's
   stage authority. Cherry-pick a sub-step (e.g. ship's merge/PR) at the matching stage only.
+  `ak:agentkit` routes *away* from flow — never invoke it mid-gate.
 - **`worktree` skill** — flow already ships `flow.sh workspace` (git-worktree-per-agent). Pure
   duplicate; never wire it.
 - **`bmad-spec` as a gate** — overlaps flow's own `/flow consistency` cross-artifact audit.

package/skills/flow/references/command-dispatch.md

@@ -9,8 +9,8 @@ is no fragment loader (ADR-0001).
 
 | User input | Runner call | Host duties after |
 |---|---|---|
-| `/flow` | `bash <skill>/runner/flow.sh status` | Relay prose `NEXT ->`, dwell, and (past 10 cards) the compact summary; nothing to author. Optional `status --json` prints one `flow_context/v1` object (`v,stage,gate,next_verb,card,dwell,load`) — **display-only**. Hosts MUST NOT dispatch `next_verb` (`next`/`card`/`card-start`/`check`/`fix-gate`/`auto`/`skip`). Default `/flow` stays prose status. |
-| `/flow resume` | `bash <skill>/runner/flow.sh resume` | Read-only session-story; no lock. Optional `resume --budget` caps in-flight cards at 5 with count line; `resume --json` same closed schema as status; display-only, never exec `next_verb`. FAIL/PASS/Never: SKILL.md STOP + Dispatch. |
+| `/flow` | `bash <skill>/runner/flow.sh status` | Relay prose `NEXT ->`, PIN v1 after NEXT_VERB (display-only, do not exec), dwell, and (past 10 cards) the compact summary; nothing to author. Compact recovery is prose status/resume, not `--json`. Optional `status --json` prints one `flow_context/v1` object (`v,stage,gate,next_verb,card,dwell,load`) — **display-only**. Hosts MUST NOT dispatch `next_verb` (`next`/`card`/`card-start`/`check`/`fix-gate`/`auto`/`skip`). Default `/flow` stays prose status. |
+| `/flow resume` | `bash <skill>/runner/flow.sh resume` | Read-only session-story; no lock. PIN v1 after NEXT_VERB, display-only, do not exec. Compact recovery is prose status/resume, not `--json`. Optional `resume --budget` caps in-flight cards at 5 with count line; `resume --json` same closed schema as status; display-only, never exec `next_verb`. FAIL/PASS/Never: SKILL.md STOP + Dispatch. |
 | `/flow next` | `bash <skill>/runner/flow.sh next` | After PASS, compare to `gate-examples.md` (not a second always-on load). FAIL/Never: SKILL.md STOP + Dispatch. |
 | `/flow assess` | `bash <skill>/runner/flow.sh assess` | Fill `flow/00-inspect.md` from EVIDENCE; Brownfield challenge in `gate-rules.md`. |
 | `/flow card` | `bash <skill>/runner/flow.sh card` | Fill per `law/CLAUDE.md`; before coding, `law/CODING.md`. |

package/skills/flow/references/flow-catalog.tsv

@@ -7,14 +7,14 @@ brownfield-assess	existing-codebase-no-flow-history	assess	brownfield current-st
 kill-doubt-idea	stage-00-or-01	status	offers the forge-idea ritual (references/forge-idea.md) at Idea/Scope: persona-driven interrogation until it hardens, proves out, or dies cheaply	-	flow
 review-ask	cards-built-pending-review	check	card review path: diff-vs-scope, allowed-files drift, contract shapes, evidence	-	flow
 deploy-ask	review-passed	status	flow has no deploy verb; status shows the Deploy stage; execution stays operator/CI	-	flow
-retro-ask	stage-verify-or-later	retro	runs the native numeric-retro ritual first (git-log recipes), then offers the operator the line	retro	flow
+retro-ask	stage-verify-or-later	retro	runs the native numeric-retro ritual first (git-log recipes), then offers the operator the line	retro|ak:retro	flow
 usage-metrics-ask	any	usage	cycle-time, gate fail-rate, per-stage dwell, command breakdown	-	flow
 parallel-multi-agent-ask	any	ready	buildable + parallel-safety hint before offering workspace add	-	flow
 help-confused	any	status	ground truth first, then explain the gate concept in one plain sentence	-	flow
 card-create-ask	all-planning-gates-passed	card	create next build card; reminds Scope/Allowed-files/Verify/Done-evidence	-	flow
-adr-decision-ask	stage-04	next	offers the native persona-debate ritual before locking a non-trivial ADR decision	ck-predict	flow
-contract-hardening-ask	stage-05	contract	offers the native edge-case decomposition ritual to harden the seam before the Contract gate	ck-scenario	flow
-security-review-ask	security-class-card	check	runs the native STRIDE ritual on every security-class card (guaranteed baseline)	ck-security	flow
-loop-fix-ask	build-verify-numeric-gap	status	offers the native loop protocol (flow.sh loop-prep/loop-log) when a fix needs more than one attempt against a numeric target	ck-loop	flow
+adr-decision-ask	stage-04	next	offers the native persona-debate ritual before locking a non-trivial ADR decision	ck-predict|ak:predict	flow
+contract-hardening-ask	stage-05	contract	offers the native edge-case decomposition ritual to harden the seam before the Contract gate	ck-scenario|ak:scenario	flow
+security-review-ask	security-class-card	check	runs the native STRIDE ritual on every security-class card (guaranteed baseline)	ck-security|ak:security	flow
+loop-fix-ask	build-verify-numeric-gap	status	offers the native loop protocol (flow.sh loop-prep/loop-log) when a fix needs more than one attempt against a numeric target	ck-loop|ak:loop	flow
 open-decision-ask	stage-02-or-03-or-05	clarify	lists ## Open decisions bullets; skill offers references/clarify.md write-back (opt-in, never a next prereq)	-	flow
 close-the-gap-ask	cards-done-verify-plan	converge	assess present code vs plan per references/converge.md, then append-only remainder cards (transactional; CONVERGED writes nothing)	-	flow

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

@@ -8,5 +8,5 @@ NOT-doing list honest about what's deferred?
   debate (architect/security/ops/user-advocate/cost) that surfaces defects while reversal
   is still cheap. Output INFORMS this challenge; it never passes the gate. Skip on a
   trivial ADR.
-- **If `ck-predict` is installed**, it is a richer alternative to the native ritual (same
-  INFORMS-only rule, opt-in-with-prompt — see `claudekit-skills.md`).
+- **If `ck-predict` or `ak:predict` is installed**, it is a richer alternative to the native ritual (same
+  INFORMS-only rule, opt-in-with-prompt — see `claudekit-skills.md` Name resolution).

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

@@ -28,6 +28,6 @@ cli=command+flags+output/exit, library=public function+args+return, skill=comman
   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.
-- **If `ck-scenario` is installed**, it is a richer 12-dimension alternative to the
+- **If `ck-scenario` or `ak:scenario` is installed**, it is a richer 12-dimension alternative to the
   native ritual (same INFORMS-only rule, opt-in-with-prompt — see
-  `claudekit-skills.md`).
+  `claudekit-skills.md` Name resolution).

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

@@ -127,7 +127,7 @@ Display-only: it reports what to run next but never executes `next_verb`.
 **Scope note (not a stability promise).** The elements above are parseable by external
 orchestrators; parse only these, never ad-hoc prose. This documents shipped
 behavior as of the current flow version (`version` in `skills/flow/SKILL.md`
-— currently 0.33.0 — surfaced as `flow_version` in telemetry). The project
+— currently 0.34.0 — surfaced as `flow_version` in telemetry). The project
 has not adopted a formal compatibility guarantee: when upgrading flow,
 re-diff this contract against the runner (`cmd_resume`, `inflight_display`,
 `_log_event`) before relying on it.

package/skills/flow/references/native-rituals.md

@@ -6,12 +6,12 @@ maintenance. Each was written fresh from public/generic patterns (persona-panel
 generic edge-case taxonomy, STRIDE — public Microsoft SDL methodology, git-log
 retrospection, iterate-to-numeric-target loops, evidence-backed harness improvement) —
 none of this text is copied from claudekit-engineer (proprietary, All Rights Reserved)
-or any other kit. Where a matching ck skill is installed, it is offered as a **richer
+or any other kit. Where a matching ck or ak skill is installed, it is offered as a **richer
 alternative**, never a requirement — see the seam files (`gate-rules.md`,
 `adversarial-review.md`, `law/RETRO.md`) for the native-first wiring, and
-`claudekit-skills.md` for the optional-enrichment annex.
+`claudekit-skills.md` for the optional-enrichment annex (Name resolution).
 
-Every ritual below follows the same rule as the ck skills it stands in for: it
+Every ritual below follows the same rule as the ck/ak skills it stands in for: it
 **informs** the gate; the gate (the `flow.sh` exit code + the semantic challenge) still
 judges. A ritual "looks good" is not a PASS.
 

package/skills/flow/references/pin-v1.txt

@@ -0,0 +1,5 @@
+PIN v1
+Never FLOW_FORCE a live session. Mechanical FAIL -> STOP.
+Security-class skip/debt -> HALT until the operator accepts in DEBT.md.
+Never mark a card done without pasted world-state evidence.
+NEXT_VERB is advisory; never auto-exec next, card, card-start, check, fix-gate, auto, or skip.

package/skills/flow/runner/flow.sh

@@ -1032,6 +1032,7 @@ cmd_resume() {
     _na="$(_next_action)"
     echo "nothing to resume - $_na"
     echo "NEXT_VERB=$(_next_verb_from "$_na")"
+    _emit_pin
     return 0
   fi
 
@@ -1388,6 +1389,18 @@ _emit_next() {
   a="$(_next_action)"
   echo "NEXT -> $a"
   echo "NEXT_VERB=$(_next_verb_from "$a")"
+  _emit_pin
+}
+
+# Verbatim PIN v1 from references/pin-v1.txt. Display-only; never a capability token.
+# Missing file: fail-loud on stderr. JSON path must not call this.
+_emit_pin() {
+  local f="$SCRIPT_DIR/../references/pin-v1.txt"
+  if [ ! -f "$f" ]; then
+    echo "FAIL: PIN file missing: $f" >&2
+    return 1
+  fi
+  tr -d '\r' < "$f"
 }
 
 # PTC-aligned load hint for JSON status/resume. Display-only — never a capability token.

package/skills-manifest.json

@@ -1,8 +1,8 @@
 {
   "source": "../skills/flow",
   "destRelative": "skills/flow",
-  "fileCount": 119,
-  "syncedAt": "2026-10-11T14:30:13.050Z",
+  "fileCount": 120,
+  "syncedAt": "2026-10-12T04:29:07.162Z",
   "fileList": [
     "SKILL.md",
     "_templates/00-idea.md",
@@ -117,6 +117,7 @@
     "references/loop-harness-2026-principles.md",
     "references/mode-work.md",
     "references/native-rituals.md",
+    "references/pin-v1.txt",
     "references/project-types.md",
     "references/stage-state-machine.md",
     "references/ui-patterns-tcr.md",