create-quiver 0.4.0 → 0.6.0

package/specs/quiver-v10-local-project-installation-guidance/slices/slice-01-local-project-installation-guidance/slice.json

@@ -0,0 +1,75 @@
+{
+  "slice_id": "slice-01-local-project-installation-guidance",
+  "ticket": "QUIVER-01",
+  "type": "docs",
+  "title": "Local Project Installation Guidance",
+  "objective": "Clarify that Quiver should be run from the target project root with `npx`, or installed as a devDependency when a pinned project-local version is needed.",
+  "description": "The README currently shows `--dir` as the primary path, which can make users think Quiver should be installed or run outside the project. This slice makes the local project root the canonical onboarding location and explicitly discourages global installation.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "local-project-installation-guidance",
+    "branch_name": "docs/QUIVER-10-local-project-installation-guidance"
+  },
+  "must": [
+    "Make `cd <project>` plus `npx create-quiver --name \"Project Name\"` the primary README flow",
+    "Keep `--dir` as an alternate path for scaffolding another directory",
+    "Document `npm install --save-dev create-quiver` as the pinned local option",
+    "Explicitly say not to install Quiver globally",
+    "Update generated project README and AI-facing docs with matching guidance"
+  ],
+  "not_included": [
+    "Changing CLI behavior",
+    "Changing package version",
+    "Publishing a release",
+    "Adding global install support"
+  ],
+  "acceptance": [
+    "The root README recommends running Quiver from the target project root",
+    "The root README discourages global installation",
+    "The generated project README contains the local-project guidance",
+    "AI-facing docs reference the local project root as the working context",
+    "Smoke checks pass"
+  ],
+  "files": [
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/AI_CONTEXT.md.template",
+    "scripts/init-docs.sh",
+    "scripts/ci/smoke-init-docs.sh",
+    "scripts/ci/smoke-create-quiver.sh",
+    "specs/quiver-v10-local-project-installation-guidance/SPEC.md",
+    "specs/quiver-v10-local-project-installation-guidance/STATUS.md",
+    "specs/quiver-v10-local-project-installation-guidance/EVIDENCE_REPORT.md",
+    "specs/quiver-v10-local-project-installation-guidance/slices/slice-01-local-project-installation-guidance/slice.json"
+  ],
+  "tests": [
+    "bash -n scripts/init-docs.sh scripts/ci/smoke-init-docs.sh scripts/ci/smoke-create-quiver.sh",
+    "bash scripts/ci/smoke-init-docs.sh",
+    "bash scripts/ci/smoke-create-quiver.sh",
+    "git diff --check"
+  ],
+  "documentation": [
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/AI_CONTEXT.md.template",
+    "specs/quiver-v10-local-project-installation-guidance/SPEC.md",
+    "specs/quiver-v10-local-project-installation-guidance/STATUS.md",
+    "specs/quiver-v10-local-project-installation-guidance/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "quiver-v09-onboarding-readme-flow"
+  ],
+  "assumptions": [
+    "`npx` is the lowest-friction default for new adopters",
+    "Teams that need pinned versions can keep `create-quiver` as a devDependency",
+    "Global installation should not be part of the recommended path"
+  ],
+  "estimated_hours": 1,
+  "actual_hours": 1,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": "2026-04-21T00:00:00Z",
+  "started_at": "2026-04-21T00:00:00Z",
+  "completed_at": "2026-04-21T00:00:00Z"
+}

package/specs/quiver-v11-existing-project-migration/EVIDENCE_REPORT.md

@@ -0,0 +1,38 @@
+# Quiver v0.11 Evidence Report
+
+**Spec:** quiver-v11-existing-project-migration
+**Last updated:** 2026-04-22
+**Status:** Completed
+
+## Summary
+
+| Slice | Acceptance criteria | Status | Evidence |
+|-------|---------------------|--------|----------|
+| slice-01 | 6 | Completed | `node -c src/create-quiver/index.js`; `bash -n scripts/init-docs.sh scripts/ci/smoke-create-quiver.sh scripts/package-quiver.sh`; `bash scripts/ci/smoke-create-quiver.sh` |
+| slice-02 | 6 | Completed | `node -c src/create-quiver/index.js`; `bash -n scripts/init-docs.sh scripts/ci/smoke-init-docs.sh scripts/ci/smoke-create-quiver.sh scripts/package-quiver.sh`; `bash scripts/ci/smoke-create-quiver.sh` |
+| slice-03 | 6 | Completed | `node -c src/create-quiver/index.js`; `bash -n scripts/init-docs.sh scripts/ci/smoke-init-docs.sh scripts/ci/smoke-create-quiver.sh scripts/package-quiver.sh`; `bash scripts/ci/smoke-init-docs.sh`; `bash scripts/ci/smoke-create-quiver.sh`; `bash scripts/package-quiver.sh` |
+
+## Evidence by Slice
+
+## Slice 01
+
+- Added `create-quiver migrate --dir <project>` with a non-destructive migration path for existing projects
+- `init-docs.sh` now respects `QUIVER_MIGRATE=1` and skips files that already exist
+- Generated projects now receive `tools/scripts/migrate-project.sh` and a `migrate` package script
+- Smoke coverage now verifies that migration restores missing files without overwriting existing edits
+
+## Slice 02
+
+- Added `.quiver/state.json` as project-local Quiver metadata
+- `init` and `migrate` create or refresh the state file with initialized and migrated version data
+- `analyze` updates `last_analysis_at` when metadata exists
+- `doctor` distinguishes between missing Quiver metadata and missing migration/upgrade artifacts
+- Smoke coverage now verifies the new state lifecycle across init, migrate, analyze, and doctor
+
+## Slice 03
+
+- Added an explicit `Upgrading Existing Projects` section to the root README and the generated project README
+- Documented both `npx` and project-local devDependency upgrade flows
+- Updated the generated onboarding docs so existing projects are guided to `migrate`, then `analyze`, then `doctor`
+- Extended smoke checks to assert the upgrade section and legacy migration preservation behavior
+- Confirmed `scripts/package-quiver.sh` still passes after the documentation and smoke updates

package/specs/quiver-v11-existing-project-migration/SPEC.md

@@ -0,0 +1,59 @@
+# Quiver v0.11 - Existing Project Migration
+
+**Date:** 2026-04-22
+**Status:** Completed
+
+Slice numbering resets here: this spec starts at `slice-01` and does not continue any previous spec's numbering.
+
+## Objective
+
+Make existing Quiver projects upgradeable without reinstalling or manually copying new templates, while preserving user-authored project context.
+
+## Scope
+
+### Included
+
+- Add a `create-quiver migrate --dir <project>` command for existing projects
+- Add or update Quiver project metadata so `doctor` can understand initialized, analyzed, and migrated state
+- Teach `doctor` to recommend migration when required files or version metadata are missing
+- Document the upgrade flow for users who already initialized Quiver in a project
+- Add smoke fixtures that simulate older generated projects and validate non-destructive migration
+
+### Excluded
+
+- Running AI providers from the CLI
+- Overwriting user-authored docs without preserving or reporting the change
+- Changing slice execution semantics
+- Publishing a release as part of this spec
+- Reworking global installation behavior
+
+## Target Upgrade Flow
+
+For a project that already has Quiver:
+
+```bash
+cd /path/to/project
+npm install --save-dev create-quiver@latest
+npx create-quiver migrate --dir .
+npx create-quiver analyze --dir .
+npx create-quiver doctor --dir .
+```
+
+Then the developer opens the AI agent and asks it to execute `docs/AI_ONBOARDING_PROMPT.md`.
+
+## Slices
+
+| Slice | Title | Status | Spec |
+|-------|-------|--------|------|
+| 01 | Non-Destructive Migrate Command | Completed | [slice-01](./slices/slice-01-non-destructive-migrate-command/slice.json) |
+| 02 | Version Metadata and Doctor Upgrade Checks | Completed | [slice-02](./slices/slice-02-version-metadata-doctor-upgrade-checks/slice.json) |
+| 03 | Upgrade Docs and Legacy Project Smokes | Completed | [slice-03](./slices/slice-03-upgrade-docs-legacy-project-smokes/slice.json) |
+
+## Definition of Done
+
+- Existing generated projects can receive new Quiver templates without deleting user edits
+- `migrate` reports copied, skipped, and already-present files
+- Quiver records enough metadata to distinguish initialized, analyzed, and migrated projects
+- `doctor` recommends `migrate` when upgrade artifacts are missing
+- README and generated docs explain the upgrade path for existing projects
+- Smokes cover a legacy project missing post-0.5 onboarding files

package/specs/quiver-v11-existing-project-migration/STATUS.md

@@ -0,0 +1,26 @@
+# Quiver v0.11 Spec Status
+
+**Spec:** quiver-v11-existing-project-migration
+**Last updated:** 2026-04-22
+
+Slice numbering is local to this spec. The first slice is `slice-01`.
+
+## Status
+
+| Slice | Title | Status | PR | Estimated hours | Actual hours |
+|-------|-------|--------|----|-----------------|--------------|
+| slice-01 | Non-Destructive Migrate Command | Completed | - | 5 | 5 |
+| slice-02 | Version Metadata and Doctor Upgrade Checks | Completed | - | 4 | 4 |
+| slice-03 | Upgrade Docs and Legacy Project Smokes | Completed | - | 3 | 3 |
+
+## Progress
+
+- Completed slices: 3 / 3
+- Estimated hours: 12
+- Actual hours: 12
+
+## Blockers
+
+| Slice | Blocker | Since | Action needed |
+|-------|---------|-------|---------------|
+| - | - | - | - |

package/specs/quiver-v11-existing-project-migration/slices/slice-01-non-destructive-migrate-command/slice.json

@@ -0,0 +1,73 @@
+{
+  "slice_id": "slice-01-non-destructive-migrate-command",
+  "ticket": "QUIVER-01",
+  "type": "feature",
+  "title": "Non-Destructive Migrate Command",
+  "objective": "Add `create-quiver migrate --dir <project>` so existing Quiver projects can receive missing framework artifacts without reinstalling or overwriting user-authored files.",
+  "description": "Users who initialized Quiver before newer onboarding files existed currently need to copy missing templates by hand. This slice adds a migration command that detects an existing Quiver project, copies missing files from the packaged template, preserves existing files, and reports exactly what happened.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "existing-project-migration",
+    "branch_name": "feature/QUIVER-01-existing-project-migration"
+  },
+  "must": [
+    "Add `migrate` mode to the `create-quiver` CLI with `--dir <project>` support",
+    "Detect an existing Quiver project using generated docs, specs, package scripts, or tools scripts",
+    "Copy missing generated framework files such as `docs/AI_ONBOARDING_PROMPT.md`, support docs, workflow docs, and tool scripts when absent",
+    "Never overwrite existing files without preserving or explicitly skipping them",
+    "Print a migration summary with copied, skipped, and already-present paths",
+    "Fail with a clear message when the target does not look like a Quiver-initialized project"
+  ],
+  "not_included": [
+    "Overwriting user-authored docs",
+    "Running `analyze` automatically",
+    "Executing AI prompts",
+    "Changing slice execution semantics",
+    "Publishing a package release"
+  ],
+  "acceptance": [
+    "`npx create-quiver migrate --dir .` runs in an existing Quiver project",
+    "Missing framework artifacts are copied from the packaged template",
+    "Existing user files are preserved",
+    "The command reports copied, skipped, and already-present paths",
+    "The command exits clearly when the target has no Quiver markers",
+    "Existing `init`, `analyze`, and `doctor` modes still work"
+  ],
+  "files": [
+    "src/create-quiver/index.js",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/package-quiver.sh",
+    "specs/quiver-v11-existing-project-migration/SPEC.md",
+    "specs/quiver-v11-existing-project-migration/STATUS.md",
+    "specs/quiver-v11-existing-project-migration/EVIDENCE_REPORT.md",
+    "specs/quiver-v11-existing-project-migration/slices/slice-01-non-destructive-migrate-command/slice.json"
+  ],
+  "tests": [
+    "node src/create-quiver/index.js migrate --dir <legacy-fixture>",
+    "node src/create-quiver/index.js doctor --dir <migrated-fixture>",
+    "bash scripts/ci/smoke-create-quiver.sh",
+    "bash scripts/package-quiver.sh",
+    "git diff --check"
+  ],
+  "documentation": [
+    "specs/quiver-v11-existing-project-migration/SPEC.md",
+    "specs/quiver-v11-existing-project-migration/STATUS.md",
+    "specs/quiver-v11-existing-project-migration/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "quiver-v10-local-project-installation-guidance"
+  ],
+  "assumptions": [
+    "Migration should be additive by default",
+    "The CLI should not infer business context during migration",
+    "Manual review remains required after migration"
+  ],
+  "estimated_hours": 5,
+  "actual_hours": 5,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": "2026-04-22T00:00:00Z",
+  "completed_at": "2026-04-22T00:00:00Z"
+}

package/specs/quiver-v11-existing-project-migration/slices/slice-02-version-metadata-doctor-upgrade-checks/slice.json

@@ -0,0 +1,71 @@
+{
+  "slice_id": "slice-02-version-metadata-doctor-upgrade-checks",
+  "ticket": "QUIVER-02",
+  "type": "feature",
+  "title": "Version Metadata and Doctor Upgrade Checks",
+  "objective": "Record Quiver project state and teach `doctor` to identify projects that need migration or analysis.",
+  "description": "After migration exists, Quiver needs a durable way to know which template version initialized or migrated the project. This slice adds metadata and extends doctor diagnostics so users get the right next command instead of guessing.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "existing-project-migration",
+    "branch_name": "feature/QUIVER-02-existing-project-migration"
+  },
+  "must": [
+    "Create or update a project-local metadata file such as `.quiver/state.json`",
+    "Record initialized version, migrated version, last migration date, and last analysis date where available",
+    "Update `init`, `migrate`, and `analyze` to maintain metadata",
+    "Teach `doctor` to report missing metadata without failing older projects unnecessarily",
+    "Teach `doctor` to recommend `npx create-quiver migrate --dir .` when required upgrade artifacts are missing",
+    "Keep metadata deterministic and free of secrets"
+  ],
+  "not_included": [
+    "Remote telemetry",
+    "User identity tracking",
+    "AI-generated metadata",
+    "Changing package publish flow"
+  ],
+  "acceptance": [
+    "Newly initialized projects include Quiver metadata",
+    "Migrated projects update metadata",
+    "`analyze` updates last analysis metadata",
+    "`doctor` distinguishes missing analysis from missing migration",
+    "Older projects without metadata receive a clear migration recommendation",
+    "Metadata contains no absolute secrets or credential values"
+  ],
+  "files": [
+    "src/create-quiver/index.js",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/ci/smoke-init-docs.sh",
+    "scripts/package-quiver.sh",
+    "specs/quiver-v11-existing-project-migration/STATUS.md",
+    "specs/quiver-v11-existing-project-migration/EVIDENCE_REPORT.md",
+    "specs/quiver-v11-existing-project-migration/slices/slice-02-version-metadata-doctor-upgrade-checks/slice.json"
+  ],
+  "tests": [
+    "init smoke verifies `.quiver/state.json`",
+    "migrate smoke verifies migration metadata",
+    "analyze smoke verifies last analysis metadata",
+    "doctor smoke verifies migration recommendation",
+    "git diff --check"
+  ],
+  "documentation": [
+    "specs/quiver-v11-existing-project-migration/STATUS.md",
+    "specs/quiver-v11-existing-project-migration/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "slice-01-non-destructive-migrate-command"
+  ],
+  "assumptions": [
+    "A local metadata file is simpler and more reliable than parsing docs for version state",
+    "Metadata should supplement, not replace, user-facing docs",
+    "Doctor should guide remediation but not run migration automatically"
+  ],
+  "estimated_hours": 4,
+  "actual_hours": 4,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": "2026-04-22T00:00:00Z",
+  "completed_at": "2026-04-22T00:00:00Z"
+}

package/specs/quiver-v11-existing-project-migration/slices/slice-03-upgrade-docs-legacy-project-smokes/slice.json

@@ -0,0 +1,78 @@
+{
+  "slice_id": "slice-03-upgrade-docs-legacy-project-smokes",
+  "ticket": "QUIVER-03",
+  "type": "docs",
+  "title": "Upgrade Docs and Legacy Project Smokes",
+  "objective": "Document the upgrade path for existing projects and add smoke coverage for legacy generated projects.",
+  "description": "Users need a clear path when they already initialized Quiver with an older package. This slice updates README and generated docs with upgrade instructions and adds fixtures or smoke setup that simulate older projects missing newer onboarding artifacts.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "existing-project-migration",
+    "branch_name": "docs/QUIVER-03-existing-project-migration"
+  },
+  "must": [
+    "Add an `Upgrading Existing Projects` section to the root README",
+    "Document both `npx` and devDependency upgrade flows",
+    "Update generated README or AI docs to mention migration for already-initialized projects",
+    "Add smoke coverage for a legacy project missing `docs/AI_ONBOARDING_PROMPT.md` and metadata",
+    "Verify migration does not overwrite edited context docs",
+    "Close the spec status and evidence"
+  ],
+  "not_included": [
+    "Publishing a release",
+    "Changing migration behavior beyond doc/test-driven fixes found during validation",
+    "Adding provider-specific AI instructions",
+    "Supporting global installation as a recommended path"
+  ],
+  "acceptance": [
+    "README explains what to do if Quiver was already initialized with an older version",
+    "Generated guidance points existing projects to `migrate`, then `analyze`, then `doctor`",
+    "Legacy project smoke proves missing files are added",
+    "Legacy project smoke proves edited docs are preserved",
+    "Package smoke passes",
+    "Spec status and evidence show all slices completed"
+  ],
+  "files": [
+    "README.md",
+    "README_FOR_AI.md",
+    "scripts/init-docs.sh",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/ci/smoke-init-docs.sh",
+    "scripts/package-quiver.sh",
+    "specs/quiver-v11-existing-project-migration/SPEC.md",
+    "specs/quiver-v11-existing-project-migration/STATUS.md",
+    "specs/quiver-v11-existing-project-migration/EVIDENCE_REPORT.md",
+    "specs/quiver-v11-existing-project-migration/slices/slice-03-upgrade-docs-legacy-project-smokes/slice.json"
+  ],
+  "tests": [
+    "bash scripts/ci/smoke-init-docs.sh",
+    "bash scripts/ci/smoke-create-quiver.sh",
+    "bash scripts/package-quiver.sh",
+    "legacy migration fixture or smoke path",
+    "git diff --check"
+  ],
+  "documentation": [
+    "README.md",
+    "README_FOR_AI.md",
+    "specs/quiver-v11-existing-project-migration/SPEC.md",
+    "specs/quiver-v11-existing-project-migration/STATUS.md",
+    "specs/quiver-v11-existing-project-migration/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "slice-01-non-destructive-migrate-command",
+    "slice-02-version-metadata-doctor-upgrade-checks"
+  ],
+  "assumptions": [
+    "Existing projects should not need to delete generated docs before upgrading",
+    "The safest upgrade order is migrate, analyze, doctor, then AI prompt",
+    "Smoke fixtures can simulate old projects by deleting newer artifacts from a generated project"
+  ],
+  "estimated_hours": 3,
+  "actual_hours": 3,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": "2026-04-22T00:00:00Z",
+  "completed_at": "2026-04-22T00:00:00Z"
+}