create-quiver 0.7.0 → 0.9.0

package/specs/quiver-v18-stabilization/slices/slice-03-publish-drafts-branch/EXECUTION_BRIEF.md

@@ -0,0 +1,73 @@
+# EXECUTION BRIEF — slice-03: Publicar rama de drafts
+
+**Spec:** quiver-v18-stabilization
+**Slice:** slice-03-publish-drafts-branch
+**Estimated time:** 5 min
+**Sin PR** — es un `git push` directo de una rama de referencia.
+
+---
+
+## ⛔ Gate obligatoria — leer antes de ejecutar cualquier cosa
+
+Este slice está **bloqueado** hasta que el mantenedor confirme explícitamente:
+
+1. Usé `quiver:plan`, `quiver:graph`, y `quiver:next` en al menos un ciclo real de trabajo.
+2. Registré una observación en `specs/quiver-v18-slice-orchestration/EVIDENCE_REPORT.md`.
+3. Confirmo que el checkpoint de v18 pasó.
+
+**Si esa confirmación no está en el prompt que te delega este slice, abortá y pedila.**
+
+---
+
+## Contexto
+
+La rama `drafts/v19-v22-orchestration-followups` existe solo localmente. Contiene 23 archivos (4 specs: v19–v22) en un único commit. ROADMAP.md y BACKLOG.md ya hacen referencia a esta rama por nombre. Publicarla en origin completa la cadena de trazabilidad y protege el trabajo ante pérdida local.
+
+No es una rama candidata a merge. Es una rama de referencia que vive indefinidamente hasta que alguna de las specs se promueva formalmente.
+
+---
+
+## Verificación previa
+
+```bash
+# 1. Confirmar que la rama existe y tiene el commit correcto
+git log drafts/v19-v22-orchestration-followups --oneline -1
+# Esperás: 13eab96 docs(drafts): park v19-v22 spec drafts pending v18 checkpoint
+
+# 2. Confirmar que NO existe ya en origin
+git ls-remote origin drafts/v19-v22-orchestration-followups
+# Esperás: salida vacía (si retorna algo, la rama ya fue publicada — slice completado)
+```
+
+---
+
+## Ejecución
+
+```bash
+GIT_SSH_COMMAND="ssh -i ~/ssh/github-personal" \
+  git push origin drafts/v19-v22-orchestration-followups
+```
+
+---
+
+## Verificación post-push
+
+```bash
+# Confirmar que el SHA remoto coincide con el local
+LOCAL_SHA=$(git rev-parse drafts/v19-v22-orchestration-followups)
+REMOTE_SHA=$(git ls-remote origin drafts/v19-v22-orchestration-followups | awk '{print $1}')
+
+echo "Local:  $LOCAL_SHA"
+echo "Remote: $REMOTE_SHA"
+
+[ "$LOCAL_SHA" = "$REMOTE_SHA" ] && echo "OK" || echo "MISMATCH — investigar"
+```
+
+---
+
+## Restricciones
+
+- **No** abras un PR para esta rama.
+- **No** hagas `--force` en ninguna circunstancia.
+- **No** edites ningún archivo en la rama antes de publicarla.
+- **No** ejecutes este slice si el gate no fue confirmado explícitamente.

package/specs/quiver-v18-stabilization/slices/slice-03-publish-drafts-branch/slice.json

@@ -0,0 +1,49 @@
+{
+  "slice_id": "slice-03-publish-drafts-branch",
+  "ticket": "QUIVER-03",
+  "type": "chore",
+  "title": "Publish `drafts/v19-v22-orchestration-followups` to origin",
+  "objective": "Push the locally-parked v19–v22 draft specs to origin so they are preserved in the remote in case of local machine loss and are accessible for future promotion.",
+  "description": "The branch `drafts/v19-v22-orchestration-followups` exists only locally. It contains 23 files across 4 spec directories (v19 Project Visibility, v20 Context Diagnostics, v21 Slice Archaeology, v22 Deferred Tooling) committed in a single commit. ROADMAP.md and BACKLOG.md already reference this branch by name. Pushing it to origin completes the traceability chain. This slice has no PR — it is a single `git push` operation. It is gated by the human checkpoint for v18: the maintainer must confirm that `plan`, `graph`, and `next` were used in real work before this slice is executed.",
+  "git": {
+    "branch_type": "chore",
+    "base_branch": null,
+    "branch_slug": "publish-drafts-v19-v22",
+    "branch_name": "drafts/v19-v22-orchestration-followups"
+  },
+  "must": [
+    "Confirm the human checkpoint for v18 was explicitly declared by the maintainer before executing",
+    "Run `git log drafts/v19-v22-orchestration-followups --oneline -1` and confirm the expected SHA is present",
+    "Push with: `GIT_SSH_COMMAND=\"ssh -i ~/ssh/github-personal\" git push origin drafts/v19-v22-orchestration-followups`",
+    "Verify with: `git ls-remote origin drafts/v19-v22-orchestration-followups` and confirm the SHA matches local"
+  ],
+  "not_included": [
+    "Opening a PR for the drafts branch — it is a reference branch, not a merge candidate",
+    "Promoting any of v19–v22 to active spec — that is a separate decision after the checkpoint",
+    "Modifying any file in the drafts branch",
+    "Any other git push"
+  ],
+  "acceptance": [
+    "Maintainer has explicitly confirmed the v18 human checkpoint",
+    "`git ls-remote origin drafts/v19-v22-orchestration-followups` returns a non-empty SHA",
+    "The returned SHA matches `git rev-parse drafts/v19-v22-orchestration-followups`"
+  ],
+  "files": [],
+  "tests": [
+    "git ls-remote origin drafts/v19-v22-orchestration-followups",
+    "git rev-parse drafts/v19-v22-orchestration-followups"
+  ],
+  "documentation": [],
+  "depends_on": [],
+  "assumptions": [
+    "The SSH key at `~/ssh/github-personal` has push access to `FabriJuncal/quiver`",
+    "The local branch `drafts/v19-v22-orchestration-followups` has not been rebased or force-reset since creation"
+  ],
+  "estimated_hours": 0.1,
+  "actual_hours": 0.1,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": "2026-05-12T00:00:00Z",
+  "started_at": "2026-05-12T00:00:00Z",
+  "completed_at": "2026-05-12T00:00:00Z"
+}

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
+}