create-quiver 0.8.0 → 0.9.0

package/.claude/settings.local.json

@@ -39,7 +39,14 @@
       "Bash(NPM_TOKEN=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 npm publish --access public)",
       "Bash(NPM_TOKEN=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 npm publish --access public)",
       "Bash(npm info *)",
-      "Bash(npm publish *)"
+      "Bash(npm publish *)",
+      "Bash(rm -rf /tmp/quiver-skip-test)",
+      "Bash(mkdir -p /tmp/quiver-skip-test)",
+      "Bash(echo '{\"name\":\"test\",\"scripts\":{}}')",
+      "Bash(ls /tmp/quiver-skip-test/node_modules/create-quiver)",
+      "Bash(rm -rf /tmp/quiver-install-test)",
+      "Bash(mkdir -p /tmp/quiver-install-test)",
+      "Bash(npm config *)"
     ]
   }
 }

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-05-14
+
+### Added
+
+- Auto-install `create-quiver` as a dev dependency after `init` and `migrate` — detects yarn/pnpm/bun/npm via lockfiles and runs the appropriate install command
+- `--skip-install` flag to suppress the dev dependency install step (useful for CI environments)
+
 ## [0.8.0] - 2026-05-13
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",

package/specs/quiver-v19-self-install-dev-dep/EVIDENCE_REPORT.md

@@ -0,0 +1,19 @@
+# Quiver v19 — Evidence Report
+
+**Spec:** quiver-v19-self-install-dev-dep
+**Date:** 2026-05-14
+**Status:** In Progress
+
+## Slice Evidence
+
+| Slice | Status | Evidence |
+|-------|--------|----------|
+| slice-01 | Ready | — |
+
+## Required Final Evidence
+
+- `npx create-quiver --name "test-project" --dir /tmp/test-project` → `cat /tmp/test-project/package.json | grep create-quiver` returns a devDependency entry
+- `ls /tmp/test-project/node_modules/create-quiver` → directory exists
+- `npx create-quiver plan` inside `/tmp/test-project` → exits 0 without `@version`
+- `npx create-quiver --skip-install --name "ci-project" --dir /tmp/ci-project` → no `node_modules/create-quiver`
+- `node --test tests/**/*.test.js` → all pass

package/specs/quiver-v19-self-install-dev-dep/SPEC.md

@@ -0,0 +1,51 @@
+# Quiver v19 — Self-Install as Dev Dependency
+
+**Date:** 2026-05-14
+**Status:** Active
+
+Slice numbering resets here. This spec starts at `slice-01`.
+
+## Problem
+
+`npx create-quiver` uses the global npx cache. After init, commands like `quiver:plan`, `quiver:graph`, and `quiver:next` in the target project may silently run the cached version instead of the latest — or fail entirely if the version in cache predates those commands. The user has no `create-quiver` in their `node_modules` unless they install it manually.
+
+## Objective
+
+After `npx create-quiver --name "foo"` (init) or `npx create-quiver migrate`, the target project's `package.json` has `create-quiver` in `devDependencies` and it is installed in `node_modules`. Subsequent `npx create-quiver` invocations in that project resolve to the local version — no cache issues, reproducible across machines.
+
+## Scope
+
+### Included
+
+- Detect the package manager in use (yarn, pnpm, bun, npm) by checking lockfiles
+- Run the appropriate install command (`npm install -D`, `yarn add -D`, `pnpm add -D`, `bun add -d`) with the exact running version
+- Skip if `create-quiver` is already present in `devDependencies`
+- Skip gracefully if no `package.json` exists in the target project
+- Add `--skip-install` flag to the CLI for CI environments
+- Apply to both `init` and `migrate` flows
+- Tests for `detectPackageManager` and `installSelfAsDevDep`
+
+### Excluded
+
+- Changing any other part of the init/migrate scaffold output
+- Supporting non-standard registries or private npm configurations
+- Auto-updating an existing create-quiver devDependency to a newer version
+
+## Acceptance Criteria
+
+1. After init, `cat package.json | jq .devDependencies` shows `"create-quiver": "^X.Y.Z"`
+2. `node_modules/create-quiver` exists in the target project after init
+3. `npx create-quiver plan` (no `@version`) works immediately after init
+4. If target project has no `package.json` → no crash, warning printed, init continues
+5. If `create-quiver` already in `devDependencies` → step skipped, no duplicate install
+6. `npx create-quiver --skip-install --name "foo"` → installs Quiver docs but skips npm install
+7. `npx create-quiver migrate --skip-install` → same skip behavior
+8. yarn/pnpm/bun projects get the right install command
+9. If install fails (no network, etc.) → warning printed, init completes without crashing
+10. `node --test tests/**/*.test.js` passes
+
+## Slices
+
+| Slice | Title | Status |
+|-------|-------|--------|
+| slice-01 | Auto-install create-quiver as dev dependency | Ready |

package/specs/quiver-v19-self-install-dev-dep/STATUS.md

@@ -0,0 +1,20 @@
+# Quiver v19 — Status
+
+**Spec:** quiver-v19-self-install-dev-dep
+**Last updated:** 2026-05-14
+
+## Status
+
+| Slice | Title | Status | PR | Estimated hours | Actual hours |
+|-------|-------|--------|----|-----------------|--------------|
+| slice-01 | Auto-install create-quiver as dev dependency | Ready | — | 1.5 | — |
+
+## Progress
+
+- Completed slices: 0 / 1
+- Estimated hours: 1.5
+- Actual hours: —
+
+## Blockers
+
+None.

package/specs/quiver-v19-self-install-dev-dep/slices/slice-01-auto-install-dev-dep/CLOSURE_BRIEF.md

@@ -0,0 +1,29 @@
+# CLOSURE BRIEF — slice-01: Auto-install create-quiver as dev dependency
+
+**Spec:** quiver-v19-self-install-dev-dep
+**Slice:** slice-01-auto-install-dev-dep
+
+---
+
+## Checklist antes de abrir el PR
+
+- [ ] `node --test tests/**/*.test.js` → exit 0, todos los tests pasan incluyendo los 7 nuevos en `init-docs.test.js`
+- [ ] Smoke con `--skip-install` → `node_modules/create-quiver` NO existe en el proyecto destino
+- [ ] Smoke sin `--skip-install` → `node_modules/create-quiver` SÍ existe y `npx create-quiver plan` funciona sin `@version`
+- [ ] Smoke con `devDependencies` preexistente → el step se saltea, no hay doble install
+- [ ] `git diff --stat HEAD` muestra exactamente 3 archivos: `src/create-quiver/lib/init-docs.js`, `src/create-quiver/index.js`, `tests/lib/init-docs.test.js`
+
+## Checklist del PR
+
+- [ ] Branch: `feature/QUIVER-01-auto-install-dev-dep` → `main`
+- [ ] Título: `feat(QUIVER-01): auto-install create-quiver as dev dependency after init`
+- [ ] Body sigue las secciones del `docs/GITFLOW_PR_GUIDE.md.template`
+- [ ] En "Evidence": output del smoke test mostrando `node_modules/create-quiver` creado y `npx create-quiver plan` funcionando
+- [ ] En "Risks / Notes": mencionar que en entornos sin red el install falla silenciosamente (expected behavior) y documentar el `--skip-install` flag
+
+## Post-merge
+
+- [ ] Actualizar `specs/quiver-v19-self-install-dev-dep/STATUS.md`: slice-01 → `Completed`, agregar PR y `actual_hours`
+- [ ] Actualizar `specs/quiver-v19-self-install-dev-dep/EVIDENCE_REPORT.md`: registrar evidencia
+- [ ] Actualizar `slice.json`: `status: completed`, `actual_hours`, timestamps
+- [ ] Evaluar si se publica `0.9.0` o si se acumula con otros cambios

package/specs/quiver-v19-self-install-dev-dep/slices/slice-01-auto-install-dev-dep/EXECUTION_BRIEF.md

@@ -0,0 +1,287 @@
+# EXECUTION BRIEF — slice-01: Auto-install create-quiver as dev dependency
+
+**Spec:** quiver-v19-self-install-dev-dep
+**Slice:** slice-01-auto-install-dev-dep
+**Branch:** `feature/QUIVER-01-auto-install-dev-dep` from `main`
+**Estimated time:** 1.5h
+
+---
+
+## Contexto
+
+`npx create-quiver` no instala el paquete en `node_modules` del proyecto destino. Después del init, comandos como `quiver:plan` fallan o usan la versión cacheada globalmente. La solución es correr el package manager del proyecto destino para instalar `create-quiver` como dev dependency inmediatamente después del init/migrate.
+
+---
+
+## Archivos a modificar
+
+1. `src/create-quiver/lib/init-docs.js` — agregar `detectPackageManager` e `installSelfAsDevDep`
+2. `src/create-quiver/index.js` — agregar `--skip-install` al parser, llamar a `installSelfAsDevDep` en init y migrate
+3. `tests/lib/init-docs.test.js` — nuevo archivo de tests
+
+No toques ningún otro archivo.
+
+---
+
+## Parte A — `src/create-quiver/lib/init-docs.js`
+
+### Paso 1: Agregar import de `execSync`
+
+Al inicio del archivo, después de los requires existentes (`fs`, `path`, `writeState`), agregar:
+
+```js
+const { execSync } = require('child_process');
+```
+
+### Paso 2: Agregar las dos funciones nuevas
+
+Agregar antes del `module.exports` al final del archivo:
+
+```js
+function detectPackageManager(projectRoot) {
+  if (fs.existsSync(path.join(projectRoot, 'bun.lockb'))) return 'bun';
+  if (fs.existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(projectRoot, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
+function installSelfAsDevDep(projectRoot, version) {
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    return 'skipped-no-package-json';
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  if (pkg.devDependencies && pkg.devDependencies['create-quiver']) {
+    return 'skipped-already-present';
+  }
+
+  const pm = detectPackageManager(projectRoot);
+  const commands = {
+    npm: `npm install -D create-quiver@${version}`,
+    yarn: `yarn add -D create-quiver@${version}`,
+    pnpm: `pnpm add -D create-quiver@${version}`,
+    bun: `bun add -d create-quiver@${version}`,
+  };
+
+  try {
+    execSync(commands[pm], { cwd: projectRoot, stdio: 'inherit' });
+    return 'installed';
+  } catch {
+    return 'failed';
+  }
+}
+```
+
+### Paso 3: Exportar las funciones nuevas
+
+Encontrá el `module.exports` actual y agregá las dos funciones nuevas:
+
+```js
+module.exports = {
+  // ... exports existentes ...
+  detectPackageManager,
+  installSelfAsDevDep,
+};
+```
+
+---
+
+## Parte B — `src/create-quiver/index.js`
+
+### Paso 1: Importar `installSelfAsDevDep`
+
+En la línea 10 donde se importa `runInitDocs`, extender el destructuring para incluir la función nueva:
+
+```js
+// Antes (aproximado):
+const { runInitDocs } = require('./lib/init-docs');
+
+// Después:
+const { runInitDocs, installSelfAsDevDep } = require('./lib/init-docs');
+```
+
+### Paso 2: Agregar `--skip-install` al parser de args
+
+Dentro de la función `parseArgs`, en el bloque donde se manejan los flags (el loop que analiza `arg`), agregar el caso nuevo junto a los otros flags booleanos (`--yes`, etc.):
+
+```js
+if (arg === '--skip-install') {
+  result.skipInstall = true;
+  continue;
+}
+```
+
+### Paso 3: Llamar a `installSelfAsDevDep` en el flujo de init
+
+El flujo init en index.js (cerca de la línea 1416) actualmente es:
+
+```js
+runInitDocs(targetDir, projectName);
+console.log(`Installed Quiver into ${targetDir}`);
+printInitNextSteps(targetDir, projectName);
+```
+
+Reemplazarlo por:
+
+```js
+runInitDocs(targetDir, projectName);
+
+if (!args.skipInstall) {
+  const installResult = installSelfAsDevDep(targetDir, CLI_VERSION);
+  if (installResult === 'installed') {
+    console.log(`Added create-quiver@${CLI_VERSION} as dev dependency`);
+  } else if (installResult === 'failed') {
+    console.warn(`Warning: could not install create-quiver automatically. Run: npm install -D create-quiver@${CLI_VERSION}`);
+  }
+}
+
+console.log(`Installed Quiver into ${targetDir}`);
+printInitNextSteps(targetDir, projectName);
+```
+
+Nota: `CLI_VERSION` ya existe en `index.js` — no lo reimportes.
+
+### Paso 4: Llamar a `installSelfAsDevDep` en el flujo de migrate
+
+Buscá el flujo de migrate en index.js (buscar `runInitDocs` con `migrateMode: true` o similar). Aplicar el mismo patrón después del call de init/migrate.
+
+---
+
+## Parte C — `tests/lib/init-docs.test.js` (archivo nuevo)
+
+Crear este archivo con el patrón del repo (`node:test`, `node:assert/strict`):
+
+```js
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const test = require('node:test');
+
+const { detectPackageManager, installSelfAsDevDep } = require('../../src/create-quiver/lib/init-docs');
+
+function makeTmpDir() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-init-test-'));
+  return { dir, cleanup: () => fs.rmSync(dir, { recursive: true, force: true }) };
+}
+
+test('detectPackageManager returns npm when no lockfile exists', () => {
+  const { dir, cleanup } = makeTmpDir();
+  try {
+    assert.equal(detectPackageManager(dir), 'npm');
+  } finally {
+    cleanup();
+  }
+});
+
+test('detectPackageManager returns yarn when yarn.lock exists', () => {
+  const { dir, cleanup } = makeTmpDir();
+  try {
+    fs.writeFileSync(path.join(dir, 'yarn.lock'), '');
+    assert.equal(detectPackageManager(dir), 'yarn');
+  } finally {
+    cleanup();
+  }
+});
+
+test('detectPackageManager returns pnpm when pnpm-lock.yaml exists', () => {
+  const { dir, cleanup } = makeTmpDir();
+  try {
+    fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+    assert.equal(detectPackageManager(dir), 'pnpm');
+  } finally {
+    cleanup();
+  }
+});
+
+test('detectPackageManager returns bun when bun.lockb exists', () => {
+  const { dir, cleanup } = makeTmpDir();
+  try {
+    fs.writeFileSync(path.join(dir, 'bun.lockb'), '');
+    assert.equal(detectPackageManager(dir), 'bun');
+  } finally {
+    cleanup();
+  }
+});
+
+test('installSelfAsDevDep returns skipped-no-package-json when no package.json', () => {
+  const { dir, cleanup } = makeTmpDir();
+  try {
+    const result = installSelfAsDevDep(dir, '0.8.0');
+    assert.equal(result, 'skipped-no-package-json');
+  } finally {
+    cleanup();
+  }
+});
+
+test('installSelfAsDevDep returns skipped-already-present when create-quiver in devDeps', () => {
+  const { dir, cleanup } = makeTmpDir();
+  try {
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({
+      name: 'test',
+      devDependencies: { 'create-quiver': '^0.7.0' },
+    }));
+    const result = installSelfAsDevDep(dir, '0.8.0');
+    assert.equal(result, 'skipped-already-present');
+  } finally {
+    cleanup();
+  }
+});
+
+test('installSelfAsDevDep returns failed when install command fails', () => {
+  const { dir, cleanup } = makeTmpDir();
+  try {
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: 'test' }));
+    // Force failure: set PATH to empty so no package manager can be found
+    const original = process.env.PATH;
+    process.env.PATH = '';
+    const result = installSelfAsDevDep(dir, '0.8.0');
+    process.env.PATH = original;
+    assert.equal(result, 'failed');
+  } finally {
+    cleanup();
+  }
+});
+```
+
+---
+
+## Verificaciones
+
+```bash
+# Tests
+node --test tests/**/*.test.js
+
+# Smoke: --skip-install no instala
+mkdir -p /tmp/quiver-skip-test && echo '{"name":"test","scripts":{}}' > /tmp/quiver-skip-test/package.json
+node bin/create-quiver.js --skip-install --name test --dir /tmp/quiver-skip-test
+ls /tmp/quiver-skip-test/node_modules/create-quiver 2>/dev/null && echo "FAIL: se instaló igual" || echo "OK: no instaló"
+
+# Smoke: sin --skip-install sí instala (requiere red)
+mkdir -p /tmp/quiver-install-test && echo '{"name":"test","scripts":{}}' > /tmp/quiver-install-test/package.json
+node bin/create-quiver.js --name test --dir /tmp/quiver-install-test
+ls /tmp/quiver-install-test/node_modules/create-quiver && echo "OK: instalado" || echo "FAIL"
+```
+
+---
+
+## Restricciones
+
+- No toques `mergePackageJson` — la lógica de install va en `installSelfAsDevDep`, no en el merge de package.json
+- No hagas `npm install` general — solo `npm install -D create-quiver@VERSION`
+- No elimines ni renombres ningún export existente de `init-docs.js`
+- No agregues dependencias externas — solo `child_process` (built-in de Node)
+- Un solo commit con los tres archivos
+
+## Mensaje de commit sugerido
+
+```
+feat(QUIVER-01): auto-install create-quiver as dev dependency after init
+
+After init or migrate, detect the target project's package manager
+(yarn/pnpm/bun/npm) and install create-quiver as a dev dependency.
+Skippable with --skip-install for CI environments.
+Resolves the npx cache issue: subsequent quiver commands in the project
+resolve to the local version without requiring @version suffix.
+```

package/specs/quiver-v19-self-install-dev-dep/slices/slice-01-auto-install-dev-dep/slice.json

@@ -0,0 +1,56 @@
+{
+  "slice_id": "slice-01-auto-install-dev-dep",
+  "ticket": "QUIVER-01",
+  "type": "feature",
+  "title": "Auto-install create-quiver as dev dependency after init/migrate",
+  "objective": "After `npx create-quiver` init or migrate, the target project has create-quiver in devDependencies and installed in node_modules. Uses the correct package manager. Skippable via --skip-install.",
+  "description": "Add two functions to init-docs.js: detectPackageManager (checks lockfiles) and installSelfAsDevDep (runs the appropriate install command). Call installSelfAsDevDep from the init and migrate flows in index.js after runInitDocs. Add --skip-install flag to the CLI arg parser.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "auto-install-dev-dep",
+    "branch_name": "feature/QUIVER-01-auto-install-dev-dep"
+  },
+  "files": [
+    "src/create-quiver/lib/init-docs.js",
+    "src/create-quiver/index.js",
+    "tests/lib/init-docs.test.js"
+  ],
+  "depends_on": [],
+  "must": [
+    "detectPackageManager(projectRoot) returns 'bun'|'pnpm'|'yarn'|'npm' based on lockfile presence",
+    "installSelfAsDevDep(projectRoot, version) runs the correct install command for the detected pm",
+    "installSelfAsDevDep skips if no package.json exists (returns 'skipped-no-package-json')",
+    "installSelfAsDevDep skips if create-quiver already in devDependencies (returns 'skipped-already-present')",
+    "installSelfAsDevDep catches install errors and returns 'failed' without throwing",
+    "--skip-install flag parsed in index.js and passed through to suppress the install step",
+    "Both init and migrate flows call installSelfAsDevDep unless --skip-install is set",
+    "Init output prints 'Added create-quiver@X.Y.Z as dev dependency' on success or a warning on skip/fail",
+    "node --test tests/**/*.test.js passes"
+  ],
+  "not_included": [
+    "Auto-updating an existing create-quiver version in devDependencies",
+    "Supporting private registries or custom npm configs",
+    "Changing the scaffold output beyond the install step message"
+  ],
+  "acceptance": [
+    "After init: package.json has create-quiver in devDependencies",
+    "After init: node_modules/create-quiver exists",
+    "npx create-quiver plan works without @version in a freshly initialized project",
+    "--skip-install suppresses the install in both init and migrate",
+    "yarn/pnpm/bun projects use the right install command",
+    "Install failure prints a warning but does not crash the init",
+    "node --test tests/**/*.test.js exits 0"
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "npx create-quiver --skip-install --name test --dir /tmp/quiver-test-skip && ls /tmp/quiver-test-skip/node_modules/create-quiver 2>/dev/null && echo FAIL || echo OK"
+  ],
+  "estimated_hours": 1.5,
+  "actual_hours": null,
+  "status": "ready",
+  "blocked_reason": null,
+  "ready_at": "2026-05-14T00:00:00Z",
+  "started_at": null,
+  "completed_at": null
+}

package/src/create-quiver/index.js

@@ -7,7 +7,7 @@ const { collectDoctorWarnings } = require('./lib/doctor');
 const { runGraph } = require('./commands/graph');
 const { runNext } = require('./commands/next');
 const { runPlan } = require('./commands/plan');
-const { initializeProjectDocs } = require('./lib/init-docs');
+const { initializeProjectDocs, installSelfAsDevDep } = require('./lib/init-docs');
 const { checkPrReadiness, checkScope, checkSliceReadiness } = require('./lib/readiness');
 const { cleanupSlice, refreshActiveSlicesBoard, startSlice } = require('./lib/lifecycle');
 const { relativePosixPath, resolveTargetRoot } = require('./lib/paths');
@@ -144,6 +144,11 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--skip-install') {
+      result.skipInstall = true;
+      continue;
+    }
+
     if (arg === '--doctor') {
       result.mode = 'doctor';
       continue;
@@ -1160,6 +1165,15 @@ function runMigrate(targetDir) {
     });
     updateStateForMigrate(projectRoot, projectName, CLI_VERSION);
 
+    if (!args.skipInstall) {
+      const installResult = installSelfAsDevDep(projectRoot, CLI_VERSION);
+      if (installResult === 'installed') {
+        console.log(`Added create-quiver@${CLI_VERSION} as dev dependency`);
+      } else if (installResult === 'failed') {
+        console.warn(`Warning: could not install create-quiver automatically. Run: npm install -D create-quiver@${CLI_VERSION}`);
+      }
+    }
+
     console.log(`Quiver migration completed for ${projectRoot}`);
     console.log('Missing workflow files were restored without overwriting existing project files.');
   } finally {
@@ -1415,6 +1429,15 @@ async function run(argv) {
     copyTemplate(templateRoot, targetDir);
     runInitDocs(targetDir, projectName);
 
+    if (!args.skipInstall) {
+      const installResult = installSelfAsDevDep(targetDir, CLI_VERSION);
+      if (installResult === 'installed') {
+        console.log(`Added create-quiver@${CLI_VERSION} as dev dependency`);
+      } else if (installResult === 'failed') {
+        console.warn(`Warning: could not install create-quiver automatically. Run: npm install -D create-quiver@${CLI_VERSION}`);
+      }
+    }
+
     console.log(`Installed Quiver into ${targetDir}`);
     printInitNextSteps(targetDir, projectName);
   } finally {

package/src/create-quiver/lib/init-docs.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const { execSync } = require('child_process');
 const { writeState } = require('./state');
 
 function ensureDir(dirPath) {
@@ -667,8 +668,44 @@ function initializeProjectDocs(options) {
   };
 }
 
+function detectPackageManager(projectRoot) {
+  if (fs.existsSync(path.join(projectRoot, 'bun.lockb'))) return 'bun';
+  if (fs.existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(projectRoot, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
+function installSelfAsDevDep(projectRoot, version) {
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    return 'skipped-no-package-json';
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  if (pkg.devDependencies && pkg.devDependencies['create-quiver']) {
+    return 'skipped-already-present';
+  }
+
+  const pm = detectPackageManager(projectRoot);
+  const commands = {
+    npm: `npm install -D create-quiver@${version}`,
+    yarn: `yarn add -D create-quiver@${version}`,
+    pnpm: `pnpm add -D create-quiver@${version}`,
+    bun: `bun add -d create-quiver@${version}`,
+  };
+
+  try {
+    execSync(commands[pm], { cwd: projectRoot, stdio: 'inherit' });
+    return 'installed';
+  } catch {
+    return 'failed';
+  }
+}
+
 module.exports = {
   initializeProjectDocs,
   writeFrontMatter,
   toProjectSlug,
+  detectPackageManager,
+  installSelfAsDevDep,
 };