@mhd-ghaith-abtah/flow 0.8.0-beta.2 → 0.8.0-beta.3

package/CHANGELOG.md

@@ -6,6 +6,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0-beta.3] — 2026-05-23
+
+### Fixed
+- **`flow doctor` now finds `flow.config.yaml` at the canonical `.claude/flow.config.yaml` path** — surfaced by a real install into kaizenpro. Doctor was checking only the legacy root-level `flow.config.yaml` path while `scaffold()` writes to `.claude/flow.config.yaml`. Result: every fresh install reported `Config ℹ not present (run /flow-init)` even though the file was sitting right there, AND the entire Adapters section was suppressed (it depends on a parsed config). Fix: `probeConfig` checks `.claude/flow.config.yaml` first then falls back to the root path for backward compat. 3 new tests pin the behavior (canonical-found / legacy-fallback / canonical-wins-when-both-exist).
+- **`flow uninstall` now removes `.claude/flow.config.yaml`** — same root cause as the doctor bug. `PROJECT_PATHS` listed only the legacy root-level `flow.config.yaml`, leaving the actually-written canonical file in place after uninstall. Fix: PROJECT_PATHS extended with `.claude/flow.config.yaml` + `.claude/flow.config.local.yaml`; legacy root paths kept for backward compat with pre-`.claude/`-convention installs.
+
+### Changed
+- **Docs now recommend `npm install -g` + `flow install-skills --scope project` as the canonical slash-command setup** — surfaced by dogfooding the `npx`-only path into kaizenpro. The pure-npx flow produces symlinks pointing at `~/.npm/_npx/<hash>/node_modules/...` which npm rotates over time; when the cache entry is purged, slash commands silently stop resolving with no error. Single `npm install -g` provides a stable symlink target at `/opt/homebrew/lib/node_modules/...` that survives until `npm uninstall`. README install section + `docs/quickstart.md` + `docs/usage.md §1` all rewritten to lead with the project-scope pattern and demote pure-npx to a "works but with caveats" section (§1d). Rationale: project-scope keeps slash commands out of unrelated Claude Code sessions; stable symlinks mean no broken-pointer debugging when the npx cache rotates. `npx -y ... install-skills --scope project` still works for one-off use, just less durable.
+
 ## [0.8.0-beta.2] — 2026-05-23
 
 ### Fixed

package/README.md

@@ -20,18 +20,21 @@ Existing per-story workflows are token-heavy. BMad's create-story re-reads epics
 
 ## Install
 
-> **Status (v0.7.2-beta.0, published 2026-05-19):** Flow is live on npm as a **beta channel**. Stable `latest` will be promoted from beta after a soak period. Expect minor breaking changes between beta releases until then.
+> **Status (v0.8.0-beta.2, published 2026-05-23):** Flow is live on npm via the `@beta` dist-tag. `@latest` still points at the older `0.7.2-beta.0` and gets promoted from `@beta` after a soak window with no critical issues. Pin to `@beta` for the new headless install + project-scope ECC + bug fixes.
 
 ```bash
-# 1. Install the Node CLI + bootstrap the Claude Code surface
+# 1. Install the Node CLI (once per machine)
 npm install -g @mhd-ghaith-abtah/flow@beta
-flow install-skills                             # one-time; symlinks 4 skills into ~/.claude/skills/
+flow --version                                  # → 0.8.0-beta.2
 
-# 2. Then EITHER (interactive):
-/flow-init                                      # inside Claude Code
+# 2. Per project — symlink the 4 skills into THIS project's .claude/skills/
+cd /path/to/project
+flow install-skills --scope project --force     # ← recommended scope for slash commands
 
-# OR (headless, no Claude Code needed):
-flow init --profile standard --yes              # chains detect → upstreams → MCPs → scaffold
+# 3. Pick an install path:
+flow init --profile standard --yes              # headless: detect → upstreams → MCPs → scaffold
+# OR, inside Claude Code opened in this project:
+/flow-init                                      # interactive
 
 # Useful at any point:
 flow plan --profile standard                    # preview without executing
@@ -42,7 +45,12 @@ git clone https://github.com/mhd-ghaith-abtah/flow.git
 cd flow && npm install && tools/dev-link.sh     # dev-mode equivalent of install-skills + PATH link
 ```
 
-The `flow install-skills` step is what makes `/flow-init` resolve in Claude Code — npm puts the package in your global node_modules, but Claude Code only scans `~/.claude/skills/`. After install-skills, both paths (interactive slash or headless CLI) reach the same orchestrator and write the same files. Override individual knobs via `--ecc-scope`, `--bmad-subset`, `--ecc-subset`. Full guide: [docs/usage.md](docs/usage.md).
+The `flow install-skills --scope project` step is what makes `/flow-init` resolve in Claude Code when opened inside the project. Two reasons project scope is the recommended default:
+
+1. **Reliable symlinks.** They point at the stable `/opt/homebrew/lib/node_modules/...` path (or your equivalent npm prefix), so they don't break the way `npx`-based symlinks do when the npx cache rotates.
+2. **No skill pollution elsewhere.** Slash commands only resolve inside this project, not in every Claude Code session you ever open.
+
+If you'd rather have `/flow-*` available globally on your machine, swap step 2 for `flow install-skills` (no `--scope` flag — defaults to `home` / `~/.claude/skills/`). For `npx`-only / no-global-install setups, see [docs/usage.md §1d](docs/usage.md#d-npx--no-install-but-with-a-caveat) — works but requires re-linking before each session. Full guide: [docs/usage.md](docs/usage.md).
 
 The installer detects your project shape, then:
 - Installs Flow's four skills (`flow-init`, `flow-sprint`, `flow-story`, `flow-doctor`)

package/docs/quickstart.md

@@ -11,20 +11,28 @@ A 10-minute path from zero to first shipped story.
 ## Install
 
 ```bash
-# 1. Install the Node CLI
+# 1. Install the Node CLI (once per machine)
 npm install -g @mhd-ghaith-abtah/flow@beta
-flow --version                                # → 0.8.0-beta.1 (or newer)
+flow --version                                # → 0.8.0-beta.2 (or newer)
 
-# 2. Bootstrap Claude Code's slash command discovery
-flow install-skills                           # symlinks 4 skills into ~/.claude/skills/
+# 2. Per project — symlink the 4 skills into THIS project's .claude/skills/
+cd /path/to/your/project
+flow install-skills --scope project --force   # ← recommended for slash commands
 
-# 3. Pick a path per project:
+# 3. Pick a path:
 flow init --profile mini --yes                # headless (no Claude Code needed)
-# OR, inside Claude Code:
+# OR, inside Claude Code opened in this project:
 /flow-init                                    # interactive Q&A
 ```
 
-`flow install-skills` is the bridge — npm puts Flow in `~/.npm-global/lib/node_modules/...` but Claude Code only scans `~/.claude/skills/<name>/`. Without that step, `/flow-init` won't resolve. Re-run after every Flow upgrade to refresh the symlinks (idempotent).
+`flow install-skills --scope project` is the bridge — npm puts Flow in `/opt/homebrew/lib/node_modules/...` but Claude Code only resolves slash commands from a scanned path (`~/.claude/skills/` for home scope, `<project>/.claude/skills/` for project scope). Per-project scope is the recommended default because:
+
+- Symlinks point at a stable path that survives until you `npm uninstall`
+- Slash commands only appear inside this project, not in every unrelated Claude Code session
+
+Re-run `flow install-skills --scope project --force` after every Flow upgrade (`npm install -g @mhd-ghaith-abtah/flow@beta`) to refresh the symlinks. It's idempotent.
+
+If you'd rather have `/flow-*` available globally on your machine instead of per-project, omit the `--scope` flag — `flow install-skills` defaults to `home` scope (`~/.claude/skills/`). See [usage.md §1](usage.md#1-installation-paths) for the full breakdown.
 
 ## What the installer does
 

package/docs/usage.md

@@ -34,51 +34,73 @@ This is the long-form reference. For the 10-minute first-install path, see [quic
 
 Flow ships in two surfaces: a Claude Code skill bundle (interactive) and a Node CLI (`flow`, headless). Both invoke the same underlying installers and write the same files.
 
-**Bootstrap order matters.** Claude Code discovers slash commands by scanning `~/.claude/skills/<name>/`. The npm package puts skill files in the install location (typically `~/.npm-global/lib/node_modules/...`), NOT in `~/.claude/skills/`. So `/flow-init` does NOT work after a bare `npm install -g`. You need to run `flow install-skills` once to symlink the four skills into Claude Code's discovery path.
+**Bootstrap order matters.** Claude Code discovers slash commands by scanning `~/.claude/skills/<name>/` (home scope) or `<project>/.claude/skills/<name>/` (project scope). The npm package puts skill files in the install location (typically `/opt/homebrew/lib/node_modules/...` on macOS Homebrew node, or `~/.npm-global/lib/node_modules/...` on other setups), NOT in any of Claude Code's discovery paths. You need to run `flow install-skills` once to symlink the four skills into a discovery path.
 
-### a. From npm (recommended)
+### a. Recommended: `npm install -g` + `flow install-skills --scope project` (per project)
+
+This is the right shape if you want **reliable slash commands** in one or more projects without polluting Claude Code's global skill set.
 
 ```bash
-# 1. Install the Node CLI
+# 1. Once on your machine — installs the `flow` CLI + provides a stable symlink target
 npm install -g @mhd-ghaith-abtah/flow@beta
-flow --version
+flow --version                                  # → 0.8.0-beta.2 (or newer)
 
-# 2. Bootstrap Claude Code surface (links 4 skills into ~/.claude/skills/)
-flow install-skills
+# 2. Per project — symlink the four skills into the project's .claude/skills/
+cd /path/to/project
+flow install-skills --scope project --force
 
-# 3. Now both paths work — pick one per project:
-flow init --profile mini --yes              # headless
-# OR, inside Claude Code:
-/flow-init                                  # interactive
+# 3. Pick your install path
+flow init --profile mini --yes                  # headless
+# OR, inside Claude Code opened in this project:
+/flow-init                                      # interactive
 ```
 
-`flow install-skills` is idempotent — re-run safely after every upgrade to refresh the symlinks. It refuses to clobber existing real directories at the target without `--force`.
+Why this combination is the best default for slash commands:
+
+- The symlinks point at `/opt/homebrew/lib/node_modules/@mhd-ghaith-abtah/flow/skills/...` — a stable path that persists until you `npm uninstall`. **Never breaks** under normal use.
+- Project-scope means `/flow-*` only resolves when Claude Code is opened inside the project. No skill pollution in unrelated projects.
+- One `npm install -g` covers any number of projects — install-skills per project is the only per-project bootstrap step.
+- Upgrading Flow (`npm install -g @mhd-ghaith-abtah/flow@beta` again later) automatically refreshes every project's symlinks. No re-bootstrap needed.
+
+### b. Variant: `npm install -g` + `flow install-skills` (user-wide)
+
+If you'd rather have slash commands available **everywhere** on your machine instead of per-project:
+
+```bash
+npm install -g @mhd-ghaith-abtah/flow@beta
+flow install-skills                             # default scope: home (~/.claude/skills/)
+```
 
-### b. install-skills scope flag
+Now `/flow-init` resolves in every Claude Code session. Re-run `flow install-skills` after each `npm install -g` upgrade.
 
-By default `flow install-skills` writes to `~/.claude/skills/` (home scope). Override:
+### c. install-skills scope flag
 
 ```bash
-flow install-skills                            # default: --scope home
-flow install-skills --scope home               # user-wide ~/.claude/skills/
-flow install-skills --scope project            # team-commit: <cwd>/.claude/skills/
-flow install-skills --scope both               # both
-flow install-skills --dry-run                  # preview
-flow install-skills --force                    # replace existing real dirs
+flow install-skills                             # default: --scope home
+flow install-skills --scope home                # user-wide ~/.claude/skills/
+flow install-skills --scope project             # team-commit: <cwd>/.claude/skills/
+flow install-skills --scope both                # both
+flow install-skills --dry-run                   # preview
+flow install-skills --force                     # replace existing real dirs
 ```
 
-The `--scope project` mode is for teams that want every contributor to get Flow's slash commands the moment they `git clone` the repo — commit `<project>/.claude/skills/flow-*` so Claude Code picks them up automatically when the session is opened inside the project. The user still needs the npm package installed because the symlinks point at it.
+`--scope project` is the team-commit pattern. Commit `<project>/.claude/skills/flow-*` so any contributor cloning the repo gets the slash commands automatically once they `npm install -g @mhd-ghaith-abtah/flow@beta` on their own machine. The symlinks point at each contributor's local npm install location, so the path is per-machine; what's committed is the four symlink files themselves.
 
-### c. `npx` — no install
+### d. `npx` — no install, but with a caveat
 
 ```bash
-npx -y @mhd-ghaith-abtah/flow@beta install-skills     # one-time bootstrap
+npx -y @mhd-ghaith-abtah/flow@beta install-skills --scope project --force
 npx -y @mhd-ghaith-abtah/flow@beta init --profile mini --yes
 ```
 
-`npx` works but the symlink targets the npx cache path, which can disappear when the cache rotates. For ongoing use, prefer `npm install -g`.
+Works for an immediate session, BUT the symlinks point at the npx cache (`~/.npm/_npx/<hash>/node_modules/...`), which npm rotates over time. When the cache entry is purged, the symlinks become broken pointers and `/flow-init` stops resolving with no error. Two ways to handle this:
 
-### d. Development clone
+- **Re-run `npx ... install-skills --scope project --force` before each session that needs slash commands.** Refreshes the symlinks against whatever the current npx cache hash is. Easy to forget.
+- **Or just use path (a) — single `npm install -g` + per-project `flow install-skills`.** Stable symlinks, slash commands always resolve.
+
+`npx` is fine for one-shot use (`flow plan`, `flow doctor`, one-off `flow init`), but for ongoing slash-command access prefer the npm-install-g path.
+
+### e. Development clone (contributors)
 
 ```bash
 git clone https://github.com/mhd-ghaith-abtah/flow.git
@@ -87,8 +109,6 @@ cd flow && npm install && tools/dev-link.sh
 
 `tools/dev-link.sh` is the dev-mode equivalent of `flow install-skills --scope home` — symlinks the four `skills/flow-*` dirs into `~/.claude/skills/` AND puts `flow` on `$PATH` from your clone. Use when you're contributing so changes to skill workflows take effect immediately.
 
-`tools/dev-link.sh` symlinks your clone into `$HOME/.claude/skills/flow-*` and onto `$PATH` as `flow`. Use when you're contributing.
-
 ### e. Verifying the install
 
 ```bash

package/lib/commands/doctor.js

@@ -131,9 +131,17 @@ function probeJson(path, scope) {
 }
 
 function probeConfig(ctx) {
-  const path = join(ctx.cwd, 'flow.config.yaml');
+  // Canonical path is .claude/flow.config.yaml (where scaffold writes).
+  // Legacy root-level flow.config.yaml is checked as a fallback for installs
+  // done before the .claude/ convention. First-match-wins.
+  const canonicalPath = join(ctx.cwd, '.claude', 'flow.config.yaml');
+  const legacyPath = join(ctx.cwd, 'flow.config.yaml');
+  const path = existsSync(canonicalPath) ? canonicalPath : legacyPath;
   const r = { path, status: '✗', error: null, parsed: null };
   if (!existsSync(path)) {
+    // Surface the canonical path in the "not present" hint so users know
+    // where to look (or where the install would write to next time).
+    r.path = canonicalPath;
     r.status = 'ℹ';
     r.error = 'not present (run /flow-init)';
     return r;

package/lib/commands/uninstall.js

@@ -26,7 +26,9 @@ const HOME_PATHS = [
 
 const PROJECT_PATHS = [
   '.claude/flow',
-  'flow.config.yaml',
+  '.claude/flow.config.yaml',          // canonical (where scaffold writes)
+  '.claude/flow.config.local.yaml',
+  'flow.config.yaml',                  // legacy root-level (for backward compat)
   'flow.config.local.yaml'
 ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhd-ghaith-abtah/flow",
-  "version": "0.8.0-beta.2",
+  "version": "0.8.0-beta.3",
   "description": "Token-light per-story workflow for Claude Code. Delegates to BMad + ECC.",
   "license": "MIT",
   "type": "module",