create-quiver 0.14.1 → 0.15.1

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-07-tests-smokes-release-readiness/EXECUTION_BRIEF.md

@@ -0,0 +1,59 @@
+# EXECUTION_BRIEF - slice-07 Tests, smokes, package dry-run, and release readiness
+
+## Context
+
+The v31 changes touch core AI command behavior and agent profile setup. Release readiness must prove backward compatibility, no-TTY safety, JSON cleanliness, and package safety.
+
+## Objective
+
+Close v31 with full validation, evidence, and release readiness without publishing npm.
+
+## Scope
+
+- tests and smoke suites
+- final docs/evidence updates
+- `CHANGELOG.md`
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- v31 spec closure files
+
+## Acceptance Criteria
+
+- Full test suite passes.
+- Smoke suites pass.
+- Package smoke and npm pack dry-run pass.
+- Spec validation passes.
+- Final evidence is recorded.
+- Known remaining risks are documented.
+
+## Technical Plan Summary
+
+Run final validation after every implementation and docs slice, then update status/evidence/PR body/closure briefs.
+
+## Suggested Steps
+
+1. Run focused tests from prior slices if needed.
+2. Run full suite.
+3. Run smoke suites.
+4. Run package safety and npm pack dry-run.
+5. Validate spec.
+6. Update final evidence and status.
+
+## Restrictions
+
+- Do not publish npm.
+- Do not skip failed tests.
+- Do not add new product scope.
+
+## Risks
+
+- Live provider validation depends on local provider auth and should be documented separately.
+- Catalog staleness remains a known operational risk.
+
+## Completion Checklist
+
+- [ ] Full tests pass.
+- [ ] Smokes pass.
+- [ ] Package dry-run passes.
+- [ ] Evidence report completed.
+- [ ] PR body updated.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-07-tests-smokes-release-readiness/slice.json

@@ -0,0 +1,94 @@
+{
+  "slice_id": "slice-07-tests-smokes-release-readiness",
+  "ticket": "QUIVER-31-07",
+  "type": "release",
+  "title": "Tests, smokes, package dry-run, and release readiness",
+  "objective": "Close the v31 spec with comprehensive validation, evidence, and package readiness.",
+  "description": "Runs full tests, smoke suites, package safety, npm pack dry-run, spec validation, and final docs/evidence closure.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v31-tests-smokes-release-readiness",
+    "branch_name": "feature/QUIVER-31-07-v31-tests-smokes-release-readiness"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/commands/flow.js",
+    "tests/**",
+    "scripts/ci/**",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/**"
+  ],
+  "expected_read_paths": [
+    "SPEC.md",
+    "README_FOR_AI.md",
+    "CHANGELOG.md",
+    "ROADMAP.md",
+    "scripts/release-quiver.sh",
+    "scripts/package-quiver.sh",
+    "tests/**"
+  ],
+  "allowed_write_paths": [
+    "CHANGELOG.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/commands/flow.js",
+    "tests/**",
+    "scripts/ci/**",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/**"
+  ],
+  "depends_on": [
+    "slice-02-interactive-agent-set-selectors",
+    "slice-03-agent-doctor-repair",
+    "slice-04-shared-preflight-provider-errors",
+    "slice-05-ai-models-list",
+    "slice-06-docs-templates-alignment"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Final release validation depends on every implementation and docs slice.",
+  "must": [
+    "Run full test suite.",
+    "Run smoke suites.",
+    "Run package safety and npm pack dry-run.",
+    "Validate spec.",
+    "Update evidence report, status, closure briefs, and PR body.",
+    "Do not publish npm without explicit release approval."
+  ],
+  "not_included": [
+    "Publishing npm.",
+    "Skipping failed tests.",
+    "Adding new product scope."
+  ],
+  "acceptance": [
+    "Full suite passes.",
+    "Smoke suites pass.",
+    "Package smoke and npm pack dry-run pass.",
+    "Spec validation passes.",
+    "Final evidence is recorded.",
+    "Known remaining risks are documented."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "npm run smoke:create-quiver",
+    "npm run smoke:doctor-fixtures",
+    "npm run smoke:guided-workflow",
+    "npm run package:quiver",
+    "npm pack --dry-run",
+    "git diff --check",
+    "node bin/create-quiver.js spec validate specs/quiver-v31-ai-model-catalog-agent-selection"
+  ],
+  "validation_hints": [
+    "Include legacy bad-profile fixture coverage.",
+    "Document any live provider smoke separately from automated tests."
+  ],
+  "estimated_hours": 6,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 5,
+  "completed_at": "2026-05-27"
+}

package/specs/quiver-v32-npx-installation-guidance/EVIDENCE_REPORT.md

@@ -0,0 +1,26 @@
+# Evidence Report - Quiver v32 npx Installation Guidance
+
+## Summary
+
+Documentation-only change. No product code was modified.
+
+## Evidence
+
+| Command | Status | Notes |
+|---|---|---|
+| `git diff --check` | Passed | No whitespace errors. |
+| `node bin/create-quiver.js spec validate specs/quiver-v32-npx-installation-guidance` | Passed | Spec package validated with one completed slice. |
+
+## Slice Evidence
+
+| Slice | Status | Evidence |
+|---|---|---|
+| `slice-00-installation-docs` | Completed | README, installation guide, troubleshooting, templates, command reference, source-of-truth docs, and PR body updated. |
+
+## Manual Review
+
+- README now explains `npx` vs local installation.
+- A dedicated installation guide explains when `node_modules` is expected.
+- Troubleshooting includes the `node_modules` confusion case.
+- Generated documentation templates include the same guidance.
+- `README_FOR_AI.md` is synchronized.

package/specs/quiver-v32-npx-installation-guidance/SPEC.md

@@ -0,0 +1,55 @@
+# Quiver v32 - npx Installation Guidance
+
+## Objective
+
+Clarify the expected installation behavior of Quiver when users run it with `npx`, especially why it does not appear in project `node_modules` unless installed explicitly as a development dependency.
+
+## Problem
+
+Users can run:
+
+```bash
+npx --yes create-quiver@latest ...
+```
+
+and expect the package to appear in `node_modules`. That is not how `npx` works, but the repository documentation did not explain the distinction clearly enough.
+
+## Scope
+
+- Add concise public-facing guidance to `README.md`.
+- Add a deeper installation guide under `docs/getting-started/`.
+- Add troubleshooting guidance for the common `node_modules` confusion.
+- Update generated-project troubleshooting and command templates.
+- Keep `README_FOR_AI.md` synchronized as the AI source of truth.
+
+## Non-Scope
+
+- No product code changes.
+- No npm publication.
+- No changes to package installation behavior.
+- No automatic local install changes.
+
+## Acceptance Criteria
+
+- Given a user runs Quiver with `npx --yes create-quiver@latest`, when they read the README, then they understand why Quiver may not appear in `node_modules`.
+- Given a team wants a pinned Quiver version, when they read the installation guide, then they can install `create-quiver` as a `devDependency`.
+- Given a user searches troubleshooting, when they see the `node_modules` entry, then they get the expected behavior, recovery path, and relevant links.
+- Given generated project docs are created from templates, when troubleshooting and command docs are inspected, then the same `npx` vs local install contract is represented.
+- Given an AI agent uses `README_FOR_AI.md`, when it explains installation, then it does not recommend global install and correctly distinguishes `npx` from local devDependency usage.
+
+## Files
+
+- `README.md`
+- `README_FOR_AI.md`
+- `docs/getting-started/installation.md`
+- `docs/reference/commands.md`
+- `docs/TROUBLESHOOTING.md`
+- `docs/TROUBLESHOOTING.md.template`
+- `docs/COMMANDS.md.template`
+- `specs/quiver-v32-npx-installation-guidance/**`
+
+## Validation
+
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v32-npx-installation-guidance`
+- Documentation review for link consistency and scope.

package/specs/quiver-v32-npx-installation-guidance/STATUS.md

@@ -0,0 +1,23 @@
+# Status - Quiver v32 npx Installation Guidance
+
+**Overall status:** Completed, pending PR
+**Created:** 2026-05-27
+**Current slice:** slice-00 completed
+
+## Summary
+
+This documentation-only spec clarifies that `npx --yes create-quiver@latest` runs Quiver from npm's execution cache and does not install it into project `node_modules`. It documents when teams should install `create-quiver` as a local `devDependency`.
+
+## Slice Status
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-00-installation-docs | Completed | README, installation guide, troubleshooting, templates, command reference, source-of-truth docs, and PR body updated. |
+
+## Current Blockers
+
+- None.
+
+## Next Step
+
+Open the documentation PR.

package/specs/quiver-v32-npx-installation-guidance/pr.md

@@ -0,0 +1,72 @@
+## Title
+
+Quiver v32: clarify npx vs local installation
+
+## Summary
+
+- Explains why `npx --yes create-quiver@latest` does not install Quiver into project `node_modules`.
+- Adds a dedicated installation guide for `npx` vs local `devDependency` usage.
+- Adds troubleshooting guidance for users who expect Quiver in `node_modules`.
+- Aligns generated docs templates and `README_FOR_AI.md`.
+
+## Scope
+
+- Public README guidance.
+- Installation guide under `docs/getting-started/`.
+- Troubleshooting entry.
+- Command reference and generated docs template notes.
+- Documentation-only WDD/SDD traceability.
+
+## Files
+
+- `README.md`
+- `README_FOR_AI.md`
+- `docs/getting-started/installation.md`
+- `docs/reference/commands.md`
+- `docs/TROUBLESHOOTING.md`
+- `docs/TROUBLESHOOTING.md.template`
+- `docs/COMMANDS.md.template`
+- `specs/quiver-v32-npx-installation-guidance/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js and npm.
+- Local Quiver source checkout.
+
+### Worktree Access
+
+- Use a dedicated docs branch for this PR.
+- No product-code changes are expected.
+
+### Run the Project
+
+This is a documentation-only change. No app runtime is needed.
+
+### Use Cases
+
+- Read the README and confirm it explains why `npx` does not populate `node_modules`.
+- Read `docs/getting-started/installation.md` and confirm it explains when to use `npx` and when to install `create-quiver` as a `devDependency`.
+- Read `docs/TROUBLESHOOTING.md` and confirm it covers the `node_modules` confusion.
+- Inspect templates to confirm generated projects inherit the same explanation.
+
+### Technical Verification
+
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v32-npx-installation-guidance`
+
+## Evidence
+
+- Documentation updated in public, reference, troubleshooting, template, and AI source-of-truth surfaces.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v32-npx-installation-guidance` passed.
+
+## Rollback
+
+Revert this documentation slice commit. No runtime behavior or package installation behavior changed.
+
+## Risks / Notes
+
+- This PR does not change how `init` or `migrate` may install local dev dependencies.
+- The guidance intentionally keeps `npx --yes create-quiver@latest` as the recommended bootstrap path.

package/specs/quiver-v32-npx-installation-guidance/slices/slice-00-installation-docs/CLOSURE_BRIEF.md

@@ -0,0 +1,31 @@
+# Closure Brief - slice-00-installation-docs
+
+## Resumen de lo realizado
+
+Se agregó documentación para explicar que `npx --yes create-quiver@latest` ejecuta Quiver desde la caché de npm y no instala el paquete dentro de `node_modules`. También se documentó cuándo conviene instalar `create-quiver` como `devDependency`.
+
+## Validación contra criterios de aceptación
+
+- README incluye explicación breve y link a la guía.
+- `docs/getting-started/installation.md` explica `npx`, caché de npm, `node_modules` y `devDependency`.
+- `docs/TROUBLESHOOTING.md` cubre la confusión de `node_modules`.
+- Templates generados fueron alineados.
+- `README_FOR_AI.md` fue actualizado como fuente de verdad.
+
+## Cambios relevantes
+
+- Public documentation now covers `npx` vs local install.
+- Generated project templates inherit the key guidance.
+- Spec package and PR body were created for traceability.
+
+## Pendientes
+
+- Abrir el PR.
+
+## Riesgos remanentes
+
+- Ninguno crítico. Esta spec no cambia comportamiento de producto.
+
+## Recomendaciones futuras
+
+- Consider adding `npx` cache behavior to `create-quiver --help` only if more users hit the same confusion.

package/specs/quiver-v32-npx-installation-guidance/slices/slice-00-installation-docs/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# Execution Brief - slice-00-installation-docs
+
+## Context
+
+Users can run Quiver with `npx --yes create-quiver@latest` and expect the package to appear in project `node_modules`. The expected npm behavior is that `npx` runs the CLI from npm's execution cache unless the package is explicitly installed locally.
+
+## Objective
+
+Document the `npx` vs local installation behavior clearly across public docs, troubleshooting, templates, and AI source-of-truth guidance.
+
+## Scope
+
+- Root README summary.
+- Dedicated installation guide.
+- Troubleshooting entry.
+- Command reference note.
+- Generated docs template note.
+- `README_FOR_AI.md` synchronization.
+
+## Criterios de aceptación
+
+- README includes a concise explanation of why Quiver may not appear in `node_modules`.
+- Installation guide explains `npx`, npm cache execution, and `devDependency` installation.
+- Troubleshooting covers the user confusion as a recoverable expected behavior.
+- Templates include the same guidance for generated projects.
+- No product code is modified.
+
+## Plan técnico resumido
+
+1. Add the public README section and link.
+2. Add `docs/getting-started/installation.md`.
+3. Add `docs/TROUBLESHOOTING.md`.
+4. Update generated troubleshooting and command templates.
+5. Update `README_FOR_AI.md`.
+6. Validate docs and spec package.
+
+## Restricciones
+
+- Do not recommend global installation.
+- Do not change runtime behavior.
+- Do not change npm package metadata.
+
+## Riesgos
+
+- Duplicating too much setup guidance in the root README.
+- Confusing `npx create-quiver` local resolution with `npx --yes create-quiver@latest` latest resolution.
+
+## Checklist de finalización
+
+- [x] README updated.
+- [x] Installation guide added.
+- [x] Troubleshooting added.
+- [x] Templates updated.
+- [x] `README_FOR_AI.md` updated.
+- [x] Validation commands run.
+- [ ] PR opened.

package/specs/quiver-v32-npx-installation-guidance/slices/slice-00-installation-docs/slice.json

@@ -0,0 +1,75 @@
+{
+  "slice_id": "slice-00-installation-docs",
+  "ticket": "QUIVER-32-00",
+  "type": "documentation",
+  "title": "npx and node_modules installation guidance",
+  "objective": "Document why Quiver does not appear in project node_modules when executed with npx, and when local devDependency installation is appropriate.",
+  "description": "Adds public README guidance, a dedicated installation guide, troubleshooting coverage, generated docs template notes, and AI source-of-truth synchronization.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v32-npx-installation-guidance",
+    "branch_name": "docs/npx-node-modules-guidance"
+  },
+  "files": [
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/getting-started/installation.md",
+    "docs/reference/commands.md",
+    "docs/TROUBLESHOOTING.md",
+    "docs/TROUBLESHOOTING.md.template",
+    "docs/COMMANDS.md.template"
+  ],
+  "expected_read_paths": [
+    "README_FOR_AI.md",
+    "README.md",
+    "docs/reference/commands.md",
+    "docs/TROUBLESHOOTING.md.template",
+    "docs/COMMANDS.md.template"
+  ],
+  "allowed_write_paths": [
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/getting-started/installation.md",
+    "docs/reference/commands.md",
+    "docs/TROUBLESHOOTING.md",
+    "docs/TROUBLESHOOTING.md.template",
+    "docs/COMMANDS.md.template",
+    "specs/quiver-v32-npx-installation-guidance/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "This is the only documentation slice in the spec.",
+  "must": [
+    "Explain that npx executes Quiver from npm's execution cache.",
+    "Explain why node_modules is not populated by npx usage.",
+    "Explain when to install create-quiver as a devDependency.",
+    "Keep README_FOR_AI synchronized.",
+    "Avoid claiming runtime behavior changes."
+  ],
+  "not_included": [
+    "Product code changes.",
+    "Package publishing.",
+    "Global install guidance."
+  ],
+  "acceptance": [
+    "README includes concise npx vs local install guidance.",
+    "A dedicated installation guide explains node_modules expectations.",
+    "Troubleshooting covers the missing node_modules symptom.",
+    "Generated docs templates include the same contract.",
+    "README_FOR_AI contains the source-of-truth explanation."
+  ],
+  "tests": [
+    "git diff --check",
+    "node bin/create-quiver.js spec validate specs/quiver-v32-npx-installation-guidance"
+  ],
+  "validation_hints": [
+    "Keep the docs concise and avoid duplicating long workflows in the root README.",
+    "Do not recommend global installation."
+  ],
+  "estimated_hours": 1,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 1,
+  "completed_at": "2026-05-27"
+}