Khắc phục cài đặt

Xem bảng này trước. Hầu hết các báo cáo khớp với một trong sáu hàng.

Hiện tượng	Cách xử lý
Không có `/flow` sau `npm i`	Chạy `npx @manhquy/flow-skill@latest`. Phải chạy CLI; chỉ cài package thì không copy gì vào skill home.
Skill cũ sau “cài lại”	Luôn dùng `@latest` để có skill v0.34.4 (installer 0.7.11). Tên package không kèm tag có thể bị lấy từ cache npx.
Claude hoặc Codex không liệt kê skill	Restart agent một lần sau lần cài đầu tiên.
`flow.sh: No such file` trên PowerShell	Gọi `…/runner/flow.cmd`, không gọi `bash`.
`durable layer DISABLED`	Cài `python3`, hoặc bỏ qua: gate cơ học vẫn chạy.
CRLF hoặc “bad interpreter”	Repo ép LF qua `.gitattributes`; clone lại nếu line ending bị sai.

Bắt đầu với doctor

bash ~/.claude/skills/flow/runner/flow.sh doctor

doctor kiểm tra bash, python, grep, git và báo cáo các path cài đặt mà nó thấy. Kết quả READY nghĩa là môi trường ổn — vấn đề nằm ở chỗ khác, thường là agent chưa được restart.

“Cài rồi mà không có /flow”

Hai nguyên nhân riêng biệt, xếp theo mức độ khả năng.

Bạn cài package thay vì chạy nó. npm i @manhquy/flow-skill chỉ thêm package vào node_modules — nó không copy cây skill tới chỗ agent tìm. Installer là CLI — bạn phải chạy nó:

npx @manhquy/flow-skill@latest

Bạn chưa restart agent. Agent liệt kê thư mục skill lúc khởi động. Claude Code cần restart; Codex cần restart rồi dùng $flow chứ không phải /flow; Cursor và Antigravity cần reload tool hoặc IDE.

Xác nhận file đã thật sự nằm đúng chỗ:

ls ~/.claude/skills/flow/SKILL.md

“Nó cài bản cũ”

Kiểm tra những gì bạn thật sự có — từ máy của bạn, không phải từ tài liệu:

npx @manhquy/flow-skill@latest --help
# --help in ra cả hai số: installer CLI, rồi skill product mà nó ship

grep -E '^\s*version:' ~/.claude/skills/flow/SKILL.md | head -1

Nếu skill trên máy cũ hơn số mà --help báo, bước copy đã không tới home đó. Chạy lại installer và chọn agent một cách tường minh.

Hai lỗi pin gây ra hầu hết các trường hợp bản cũ:

Pin nhầm version skill product trên npm. Số đó không phải version của package npm đã publish. Hãy pin version của installer CLI, hoặc dùng @latest để lấy skill hiện tại.
Dùng tag @rc — đã bị loại bỏ từ lâu.

Nếu npm báo No matching version found, gần như chắc chắn bạn đã pin số skill product. Dùng @latest hoặc pin installer. Hai số là gì và vì sao chúng khác nhau: xem Hai số version.

Windows: PowerShell resolve nhầm bash

Trong PowerShell hoặc cmd — kể cả trong Codex — lệnh bash đứng một mình thường rẽ sang WSL tại C:\WINDOWS\system32\bash.exe. WSL không đọc được path C:/... hoặc /c/..., nên bạn sẽ gặp fail No such file or directory và harness trông như hỏng dù không hỏng.

Hãy dùng launcher — nó tự tìm Git Bash và truyền path mà Git Bash chấp nhận:

& "$env:USERPROFILE\.codex\skills\flow\runner\flow.cmd" status

Chỉ gọi bash flow.sh trực tiếp khi đã xác nhận bash là Git Bash.

“durable layer DISABLED”

Đây là chế độ suy giảm (degraded), không phải fail. Lớp bền vững là store Python + SQLite cho intake, story, trace, decision, backlog. Không có python3 thì gate cơ học và mọi check stage/card vẫn chạy. Bạn chỉ mất bộ nhớ xuyên session — nên /flow recall sẽ đọc lại được ít hơn. Cài python3 để bật lại.

Vẫn kẹt

Thu thập ba thứ trước khi hỏi: output đầy đủ của doctor, hai số version mà --help in ra, và câu lệnh đã chạy kèm thông báo lỗi. Mở issue tại github.com/manhquydev/flow-skill.

Đường cài đặt khác

Installer npm (npx @manhquy/flow-skill@latest) là đường cài đặt được khuyến nghị cho skill v0.34.4. Các đường khác tồn tại dành cho contributor và máy air-gapped.

Từ git checkout:

bash install.sh global          # hoặc: pwsh install.ps1 global  trên Windows
bash install.sh project [dir]   # skill Claude theo project

bash install.sh global đồng bộ mọi agent home mà nó nhận diện được, rồi chạy bước doctor. bash install.sh project [dir] cài skill Claude theo project. Trên Windows dùng pwsh install.ps1 global — vì lệnh bash đứng một mình trong PowerShell thường là WSL và không đọc được path Windows.

Claude Code cũng có thể thêm repo làm plugin marketplace, rồi cài flow@flow-marketplace.

Đường thủ công hoàn toàn: copy skills/flow/ tới ~/.claude/skills/flow/ rồi chmod +x runner/flow.sh. Mọi kênh cài đặt ghi cùng một cây, nên bạn đổi kênh cài mà không cần tạo lại gate hay card nào.

Lệnh chi tiết và ghi chú theo nền tảng: README_VN.md

Flag CLI cài đặt

npx @manhquy/flow-skill@latest

Cần Node.js 22.14 trở lên. Luôn ghi @latest (ship skill v0.34.4). Lệnh npx @manhquy/flow-skill đứng một mình (không kèm tag) có thể bị lấy từ cache npx và âm thầm chạy bản cũ.

Giữ nguyên văn; đừng diễn giải lại nghĩa của flag. --project chỉ áp dụng cho claude.

npx @manhquy/flow-skill@latest --yes
npx @manhquy/flow-skill@latest --yes --target claude
npx @manhquy/flow-skill@latest --yes -t claude -t codex
npx @manhquy/flow-skill@latest --yes --all
npx @manhquy/flow-skill@latest --yes --project --dir .
npx @manhquy/flow-skill@latest --yes --all --dry-run --json

Flag	Ý nghĩa
`-y`, `--yes`	Bỏ qua prompt; cài selection mặc định (đã nhận diện + Claude)
`-t`, `--target <name>`	Target (có thể lặp lại hoặc comma-separated)
`--all`	Mọi target, kể cả chưa được nhận diện
`--project`	Phạm vi project. Chỉ Claude → `<dir>/.claude/skills/flow`
`--dir <path>`	Thư mục project (kéo theo `--project`; mặc định là cwd)
`--json`	JSONL events (`plan`, `install:*`, `summary`)
`--dry-run`	In plan ra; không ghi xuống đĩa
`-h`, `--help`	Trợ giúp. `--help` in ra cả hai số version.

--project chỉ hỗ trợ claude. Kết hợp target khác thì exit 2.

Nên	Không
`npx @manhquy/flow-skill@latest`	`npx @manhquy/flow-skill` đứng một mình — không kèm tag (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.11` nếu cần	Pin npm `@0.34.4` (version skill ≠ version package)
Ưu tiên `@latest`	`@rc` (đã bị loại bỏ từ lâu)

Package: @manhquy/flow-skill trên npm. Nghĩa của flag được giữ cùng installer: npm-wrapper/README_VN.md.

Đường dẫn cài đặt

Installer copy cùng một cây skill vào mọi agent home bạn chọn. Không có gì được chia sẻ giữa các home — mỗi home là một bản copy đầy đủ.

Theo agent

Agent	Path	Gọi
Claude Code	`~/.claude/skills/flow` (hoặc project-local `.claude/skills/flow`)	`/flow`
Codex CLI	`~/.codex/skills/flow`	`$flow`. Restart Codex sau cài
Agents home	`~/.agents/skills/flow`	theo host
Antigravity	`~/.gemini/antigravity-cli/skills/flow` (CLI) và `~/.gemini/config/skills/flow` (IDE)	`/flow` sau reload
Cursor	`~/.cursor/skills/flow`	panel agent skills sau reload

Antigravity có hai home vì CLI và IDE đọc hai thư mục khác nhau. Cả hai chứa cùng một bundle SKILL.md; chạy agy inspect để xác nhận skill đã được phát hiện.

Bên trong một skill home

Path	Nội dung
`SKILL.md`	Cửa vào lớp ngữ nghĩa: dispatch, đứng gác ở gate, orchestration. Mang `metadata.version`.
`runner/flow.sh`	Engine cơ học. `runner/flow.cmd` là launcher Windows.
`harness/`	Lớp bền vững (Python + SQLite).
`law/`	Luật phiên build `CLAUDE.md`, luật UI `DESIGN.md`, `RETRO.md`.
`references/`	Playbook ngữ nghĩa: luật gate, concierge, loại dự án, mapping agent, v.v.
`_templates/`	Các artifact có gate mà runner copy vào dự án. Đừng sửa trong lúc chạy.
`playbooks/`	Tri thức về stack. Đọc trước khi build trên stack đó, đóng góp lại sau.

File dự án nằm đâu

Skill home giữ harness. Dự án của bạn giữ work — nằm dưới thư mục mà bạn chạy lệnh từ đó:

flow/00-idea.md .. 05-contract.md   artifact planning, có gate
cards/C-NNN.md                      đơn vị shipping
MODE, PROJECT_TYPE                  mode soạn thảo và loại dự án
RETRO.md, DEBT.md, AUTO-LOG.md      sổ cái
DESIGN.md                           luật UI của dự án
.flow/harness.db                    bản ghi bền vững

Ghi đè root dự án bằng FLOW_PROJECT_ROOT. Chạy từ thư mục con không có flow/ riêng thì nhận dự án flow tổ tiên gần nhất và in một dòng ra stderr — thay vì tạo root thứ hai bị phân mảnh.

KB liên dự án

/flow promote <playbook.md> copy playbook tới ~/.claude/flow/playbooks — nơi /flow recall hiện nó ở mọi dự án, chứ không chỉ dự án nơi nó được học.

Phụ thuộc runtime

Phụ thuộc	Cần cho
`bash`	Engine cơ học. Trên Windows nghĩa là Git Bash. Dùng `runner/flow.cmd`.
`python3`	Khuyến nghị. Chạy lớp harness bền vững. Thiếu nó, gate vẫn chạy nhưng lớp SQLite tắt.
`git`	Tùy chọn. Cần cho worktree và `/flow auto`.
Node.js ≥ 22.14	Chỉ cần cho npm installer, không phải cho skill lúc chạy.

Xác nhận một home

grep -E '^\s*version:' ~/.claude/skills/flow/SKILL.md | head -1
bash ~/.claude/skills/flow/runner/flow.sh doctor

Biến môi trường

Runner đọc một số biến FLOW_*. Đây là những biến được ghi lại để dùng hằng ngày; tập đầy đủ nằm trong source của runner.

Biến	Hiệu lực
`FLOW_PROJECT_ROOT`	Ghi đè root dự án thay vì dò tìm theo cây thư mục.
`FLOW_SESSION_ID`	Id session ổn định. Export một lần mỗi session và truyền vào mọi lời gọi để được bảo vệ concurrency cứng thay vì cảnh báo.
`FLOW_LOCK_TTL`	Số giây trước khi `flow/.lock` tự reclaim. Mặc định 900.
`FLOW_FORCE`	Đặt `1` để chiếm lock bạn chắc chắn đã chết.
`FLOW_LOG_DISABLE` / `DO_NOT_TRACK`	Tắt usage-log JSONL cục bộ mà `/flow usage` tổng hợp. Log này vốn chỉ lưu cục bộ.
`FLOW_EVAL_RETRY_BACKOFF`	Thời gian backoff retry (tính bằng giây) cho batch eval tính phí. Mặc định 5; đặt 0 khi test.

Không có FLOW_SESSION_ID, runner không chứng minh được session cạnh tranh có thật sự khác không — nên nó chỉ cảnh báo chứ không chặn. Đó là lý do export biến này quan trọng trên máy dùng chung.

Định nghĩa chuẩn: skills/flow/runner/flow.sh

Hai số version

flow publish hai số version, và chúng không khớp nhau. Đó là chủ đích, không phải drift. --help in ra cả hai số. Hãy kiểm tra chúng từ máy của bạn, chứ không phải từ tài liệu nào.

Cái gì	Nó version cái gì
Skill product	Các gate, `SKILL.md`, runner, references, templates — những thứ phán xét build của bạn. Nằm trong metadata của `SKILL.md`.
npm installer	CLI `@manhquy/flow-skill` copy skill vào agent home. Version nằm trên package npm.

npx @manhquy/flow-skill@latest --help
# flow-skill v0.7.11 (ships skill v0.34.4)

grep -E '^\s*version:' ~/.claude/skills/flow/SKILL.md | head -1

Vì sao hai số

Chúng version cho các artifact khác nhau, với nhịp thay đổi khác nhau.

  monorepo skills/flow/  --npm run sync-->  npm-wrapper/skills/flow  --npm pack-->  registry
         |                                         |
         | install.sh / agent skill homes          | npx @manhquy/flow-skill@latest
         v                                         v
  ~/.claude/skills/flow                     same tree via installer CLI

Skill product chính là harness. Version của nó điều khiển check coherence và các trường telemetry trong lớp bền vững — nên dự án luôn nói được mình được build dưới ngữ nghĩa gate nào. Nó đổi mỗi khi gate, stage hoặc playbook tham chiếu đổi — nghĩa là khá thường xuyên.

Package npm chỉ version installer CLI: nhận diện agent, multi-select tương tác, file được copy đi đâu, các flag. Bề mặt đó nhỏ và ổn định. Publish installer version mới chỉ vì luật gate đổi sẽ là nói dối về thứ thực sự đã đổi — và buộc user phải suy luận về một con số chẳng nói lên điều gì với họ.

Gộp hai số lại nghĩa là hoặc bump installer mỗi lần đổi gate, hoặc đóng băng version gate theo nhịp phát hành installer. Cả hai đều tệ hơn việc giải thích bằng một bảng.

Sai lầm thường gặp và cách tránh

Lỗi phổ biến nhất là pin nhầm số. Version của skill product không phải version của package npm đã publish. Hãy pin installer CLI nếu cần bản cố định — còn tốt nhất cho hầu hết mọi người là @latest.

# Sai: pin version skill product (không phải version package npm)
# Đúng: pin version installer CLI, hoặc dùng @latest cho skill hiện tại
npx @manhquy/flow-skill@latest

Skill mới nhất hiện nằm trên @latest (0.7.11 ship skill 0.34.4). Lệnh npx @manhquy/flow-skill đứng một mình (không kèm tag) có thể bị lấy từ cache npx và âm thầm chạy bản cũ. Tag @rc đã bị loại bỏ từ lâu — đừng dùng. Nếu npm báo No matching version found, gần như chắc chắn bạn đã pin số skill product. --help in ra cả hai số — hãy pin số của installer.

Số nào quan trọng với bạn

Nếu bạn dùng flow, skill product là con số mô tả trải nghiệm: nó cho biết bạn có gate nào và lệnh nào. Version installer chỉ quan trọng khi debug lần cài đặt hoặc pin một bản cố định.

Nếu bạn báo lỗi, hãy đưa cả hai số. --help in chúng cùng một dòng — đó chính là lý do dòng đó tồn tại.

Kiểm drift trong một dự án

/flow coherence

Gắn cờ khi lệch version giữa các trường version đã khai báo — lát cắt doc-versus-code giá rẻ của lattice drift. Chỉ cảnh báo: gắn cờ chứ không tự sửa.

Cài đặt và lần chạy đầu · Nhật ký thay đổi