インストールのトラブルシューティング

まずこの表を上から当たる——大半の報告はこの6行のどれかに一致する。

症状	修正
`npm i` 後に `/flow` がない	`npx @manhquy/flow-skill@latest` を実行する。CLIを実行しなければならない。パッケージのインストールだけではスキルホームに何もコピーされない。
「再インストール」後に古いスキル	スキルv0.34.4（インストーラ0.7.11）には常に `@latest` を使う。ベアなパッケージ名はnpxキャッシュから出ることがある。
ClaudeやCodexがスキルを列挙しない	初回インストール後にエージェントを完全に再起動する。
PowerShellで `flow.sh: No such file`	`bash` ではなく `…/runner/flow.cmd` を呼ぶ。
`durable layer DISABLED`	`python3` をインストールする。無視も可——機械ゲートは動く。
CRLFや “bad interpreter”	リポジトリは `.gitattributes` でLFを強制する。行末が壊れたら再クローンする。

doctorから始める

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

doctor はbash、python、grep、gitをチェックし、見えるインストールパスを報告する。READY なら環境は正常で、問題は他にある——大抵はエージェントの再起動忘れだ。

「インストールしたのに /flow がない」

2つの異なる原因。可能性の順だ。

パッケージをインストールして実行していない。 npm i @manhquy/flow-skill は node_modules フォルダにパッケージを足す。エージェントが見る場所にスキルツリーをコピーしない。インストーラは実行するCLIだ：

npx @manhquy/flow-skill@latest

エージェントを再起動していない。 エージェントは起動時にスキルディレクトリを列挙する。Claude Codeは再起動が必要。Codexは再起動の後に /flow ではなく $flow。CursorとAntigravityはツールやIDEのリロードが必要だ。

ファイルが実際に着地したか確認する：

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

「古いバージョンが入った」

何を持っているか、文書ではなくマシンから確認する：

npx @manhquy/flow-skill@latest --help
# --help は両方の数字を出力する：インストーラCLI、次に出荷するスキル製品

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

インストール済みスキルバージョンが --help の報告より古ければ、コピー段階がそのホームに届いていない——インストーラを再実行し、エージェントを明示的に選ぶ。

古いインストールの大半は2つのpinミスが原因だ：

npm上でスキル製品バージョンをpinする。その数字は公開パッケージバージョンではない。インストーラCLIバージョンをpinするか、@latest を使う。
@rc タグを使う。引退済みで古い。

npmが No matching version found と言ったら、スキル製品番号をpinしている。@latest を使うか、インストーラをpinする。2つの数字と違う理由は 2つのバージョン番号。

Windows：PowerShellが間違ったbashを解決する

PowerShellやcmd——Codex内も含む——では、ベアな bash は大抵 C:\WINDOWS\system32\bash.exe のWSLに解決する。WSLは C:/... や /c/... パスを読めない。No such file or directory で落ち、ハーネスが壊れていないのに壊れて見える。

ランチャーを使う。Git Bashを見つけて、受け付けるパスを渡す：

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

bash がGit Bashであることを確認してから、直接 bash flow.sh を呼ぶ。

「durable layer DISABLED」

これは縮退モードであり、失敗ではない。耐久層はintake・story・trace・decision・backlog記録のためのPython + SQLiteストアだ。python3 がなくても機械ゲートと全ステージ・カードチェックは動く——失うのはセッションを越えた記憶であり、/flow recall の読み戻しが減る。python3 をインストールすれば再有効化される。

まだ詰まったら

助けを求める前に3つ集める：doctor 出力の全文、--help が出力する2つのバージョン番号、エラーテキスト付きの正確なコマンド。github.com/manhquydev/flow-skill にissueを開く。

代替インストールパス

npmインストーラ npx @manhquy/flow-skill@latest はスキルv0.34.4の推奨経路だ。代替はコントリビュータとエアギャップマシン向けに存在する。

gitチェックアウトから：

bash install.sh global          # または Windows では: pwsh install.ps1 global
bash install.sh project [dir]   # プロジェクトローカルのClaudeスキル

bash install.sh global は検出した全エージェントホームに同期し、doctor段階を実行する。bash install.sh project [dir] はプロジェクトローカルのClaudeスキルをインストールする。Windowsでは代わりに pwsh install.ps1 global を使う。PowerShellのベアな bash は大抵WSLで、Windowsパスを読めないためだ。

Claude Codeはリポジトリをプラグインマーケットプレイスとして追加し、flow@flow-marketplace をインストールすることもできる。

完全手動パスは skills/flow/ を ~/.claude/skills/flow/ にコピーし、runner/flow.sh を実行可能にすることだ。どのチャネルも同じツリーを書く。プロジェクトはゲートやカードを再発行せずにチャネルを切り替えられる。

コマンドとプラットフォーム注意：README.md

インストールCLIフラグ

npx @manhquy/flow-skill@latest

Node.js 22.14以上が必要だ。常に @latest を付ける（スキルv0.34.4を出荷）——ベアな npx @manhquy/flow-skill はnpxキャッシュから出て古いコピーを再実行することがある。

コピーして使う。フラグの意味を言い換えない。--project は 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

フラグ	意味
`-y`, `--yes`	プロンプトをスキップ。デフォルト選択（検出済み + Claude）をインストール
`-t`, `--target <name>`	ターゲット（反復可・カンマ区切り可）
`--all`	検出の有無にかかわらず全ターゲット
`--project`	プロジェクトスコープ——Claudeのみ → `<dir>/.claude/skills/flow`
`--dir <path>`	プロジェクトディレクトリ（`--project` を含意。デフォルト：cwd）
`--json`	JSONLイベント（`plan`、`install:*`、`summary`）
`--dry-run`	計画を出力。書き込まない
`-h`, `--help`	ヘルプ。`--help` は両方のバージョン番号を出力

--project は claude のみ支援する。他ターゲットとの --project は exit 2 だ。

する	しない
`npx @manhquy/flow-skill@latest`	ベアな `npx @manhquy/flow-skill`（古いnpxキャッシュ）
スキルをコピーするためにCLIを実行	`npm i` のみ（パッケージだけ。エージェントホームにスキルファイルなし）
必要ならインストーラ `@0.7.11` をpin	npm `@0.34.4` をpin（スキルバージョン ≠ パッケージバージョン）
`@latest` を優先	`@rc`（引退 / 古い）

パッケージ：npmの @manhquy/flow-skill。フラグの意味はインストーラと共にある：npm-wrapper/README.md。

インストールパス

インストーラは同じスキルツリーを、選んだ全エージェントホームにコピーする。ホーム間で共有はない——各々が完全なコピーだ。

エージェントごと

エージェント	パス	呼び出し
Claude Code	`~/.claude/skills/flow`（またはプロジェクトローカルの `.claude/skills/flow`）	`/flow`
Codex CLI	`~/.codex/skills/flow`	`$flow`——インストール後にCodexを再起動
Agents home	`~/.agents/skills/flow`	ホスト依存
Antigravity	`~/.gemini/antigravity-cli/skills/flow`（CLI）と `~/.gemini/config/skills/flow`（IDE）	リロード後に `/flow`
Cursor	`~/.cursor/skills/flow`	リロード後にエージェントスキルパネル

Antigravityが2つのホームを持つのは、CLIとIDEが異なるディレクトリを読むためだ。両方に同じ SKILL.md バンドルだ。agy inspect を実行して発見を確認する。

スキルホームの中身

パス	内容
`SKILL.md`	意味層の入口：ディスパッチ、ゲートキーピング、オーケストレーション。`metadata.version` を持つ。
`runner/flow.sh`	機械エンジン。`runner/flow.cmd` はWindowsランチャー。
`harness/`	耐久層（Python + SQLite）。
`law/`	`CLAUDE.md` ビルドセッションlaw、`DESIGN.md` UI law、`RETRO.md`。
`references/`	意味プレイブック：ゲート規則、コンシェルジュ、プロジェクトタイプ、エージェント対応など。
`_templates/`	ランナーがプロジェクトにコピーするゲート付き成果物。実行中に編集しない。
`playbooks/`	スタック知識——そのスタックでビルドする前に読み、後に収穫する。

プロジェクトファイルの行き先

スキルホームはハーネスを保持する。プロジェクトは作業を保持する。実行したディレクトリ配下に：

flow/00-idea.md .. 05-contract.md   計画成果物、ゲート付き
cards/C-NNN.md                      出荷単位
MODE, PROJECT_TYPE                  オーサリングモードとプロジェクトタイプ
RETRO.md, DEBT.md, AUTO-LOG.md      台帳
DESIGN.md                           プロジェクトUI law
.flow/harness.db                    耐久記録

FLOW_PROJECT_ROOT でプロジェクトルートを上書きする。自分の flow/ を持たないサブディレクトリからの実行は、断片化した第2ルートを作るのではなく、最も近い祖先のflowプロジェクトを採用し、stderrにメモを出力する。

クロスプロジェクトのナレッジベース

/flow promote <playbook.md> はプレイブックを ~/.claude/flow/playbooks にコピーする。/flow recall は来たプロジェクトだけでなく全プロジェクトでそれを浮かべる。

ランタイム依存

依存	用途
`bash`	機械エンジン。WindowsではGit Bashのこと——`runner/flow.cmd` を使う。
`python3`	推奨。耐久ハーネスを動かす。なくてもゲートは動き、SQLite層だけ無効になる。
`git`	任意。worktreeと `/flow auto` に必要。
Node.js ≥ 22.14	npmインストーラのみ。実行時のスキルには不要。

ホームの検証

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

環境変数

ランナーは多数の FLOW_* 変数を読む。日常使い向けに文書化されたものがこれだ。完全な集合はランナーソースに定義される。

変数	効果
`FLOW_PROJECT_ROOT`	ディレクトリ探索に頼らずプロジェクトルートを上書きする。
`FLOW_SESSION_ID`	安定したセッション識別子。セッションごとに一度exportし、毎呼び出しに渡すと、警告ではなく硬い並行保護が得られる。
`FLOW_LOCK_TTL`	`flow/.lock` が自動回収されるまでの秒数。デフォルト900。
`FLOW_FORCE`	死んでいると確信するロックを奪取するために `1` に設定する。
`FLOW_LOG_DISABLE` / `DO_NOT_TRACK`	`/flow usage` が集計するローカルJSONL使用ログを無効化する。どちらにせよローカルのみだ。
`FLOW_EVAL_RETRY_BACKOFF`	課金系evalバッチのリトライバックオフ（秒）。デフォルト5。テストでは0にする。

FLOW_SESSION_ID がないと、ランナーは競合セッションが別物であることを証明できず、止まるのではなく警告する——共有マシンではexportが重要な理由だ。

権威ある定義：skills/flow/runner/flow.sh

2つのバージョン番号

flow は2つのバージョン番号を発行し、一致しない。意図的であり、漂流ではない。--help は両方の数字を出力する。どの文書からではなく、自分のマシンで確認すること。

何	バージョンを付ける対象
スキル製品	ゲート、`SKILL.md`、ランナー、reference、テンプレート——ビルドを裁くもの。`SKILL.md` メタデータに生きる。
npmインストーラ	エージェントホームにスキルをコピーする `@manhquy/flow-skill` CLI。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

2つの数字の理由

異なる成果物に、異なる変化率でバージョンを付ける。

  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

スキル製品はハーネスそのものだ。そのバージョンは coherence チェックと耐久層に記録されるテレメトリフィールドを駆動する。プロジェクトは常に、どのゲート意味論の下でビルドされたかを言える。ゲート・ステージ・referenceプレイブックが変わるたびに変わる——頻繁だ。

npmパッケージはインストーラCLIにだけバージョンを付ける：エージェント検出、対話型マルチセレクト、ファイルのコピー先、フラグ。その面は小さく安定している。ゲート規則が変わったからといって新しいインストーラバージョンを発行するのは、何が変わったかについての嘘になる。ユーザーに何も語らない数字について考えさせる。

2つを畳むと、ゲート変更のたびにインストーラをbumpするか、ゲートバージョンをインストーラのリリース周期に凍結するかになる。どちらも1つの表を説明するより悪い。

起きるミスと避け方

失敗モードは間違った数字のpinだ。スキル製品バージョンは公開npmパッケージバージョンではない。固定リリースが必要ならインストーラCLIをpinする。ほぼ全員には @latest が良い。

# 間違い——スキル製品バージョンをpinする（npmパッケージバージョンではない）
# 正しい——インストーラCLIバージョンをpinするか、現在のスキルには @latest を使う
npx @manhquy/flow-skill@latest

今、最新のスキルは @latest 上にある（0.7.11 がスキル 0.34.4 を出荷）。ベアな npx @manhquy/flow-skill はnpxキャッシュから出て、静かに古いコピーを再実行することがある。@rc タグは引退済み。使うな。

npmが No matching version found と報告したら、ほぼ確実にスキル製品番号をpinしている。--help は両方の数字を出力する。インストーラの方をpinする。

どちらの数字があなたに関係するか

flowを使うなら、スキル製品バージョンが体験を記述する——どのゲートとどのコマンドを持っているかを告げる。インストーラバージョンが関係するのは、インストールのデバッグかビルドのpinのときだけだ。

問題を報告するなら、両方出す。--help は両方を1行で出力する。その行が存在するのはそのためだ。

プロジェクト内の漂流チェック

/flow coherence

宣言されたバージョンフィールド間の漂流を旗立てする——ドリフト格子の安い文書対コードの断片だ。助言的だ：旗を立てる。自動修正しない。

インストールと初回実行 · 変更履歴