create-quiver 0.5.0 → 0.6.0

package/README.md

@@ -47,7 +47,27 @@ The analyzer creates `docs/PROJECT_SCAN.json` and `docs/PROJECT_MAP.md`. These f
 
 The doctor checks the generated project contract and prints the next workflow steps. If the scan artifacts are missing, it recommends `npx create-quiver analyze --dir .` first.
 
-### 3. Ask The AI To Prepare Context
+### 3. Upgrade Existing Projects
+
+If the project already had Quiver from an older version, upgrade it from the project root:
+
+```bash
+cd /path/to/your-project
+npx create-quiver migrate --dir .
+npx create-quiver analyze --dir .
+npx create-quiver doctor --dir .
+```
+
+If your team prefers a pinned local dependency, update the package first and then run the same flow:
+
+```bash
+npm install --save-dev create-quiver@latest
+npx create-quiver migrate --dir .
+npx create-quiver analyze --dir .
+npx create-quiver doctor --dir .
+```
+
+### 4. Ask The AI To Prepare Context
 
 Open your AI agent in the target project and run this short handoff:
 
@@ -59,7 +79,7 @@ Prepare the project context docs and report assumptions, risks, and files change
 
 The AI should use the scan artifacts to prepare `docs/AI_CONTEXT.md`, `docs/CONTEXTO.md`, `docs/STATUS.md`, and the initial project spec. The developer should review those documentation changes before implementation work starts.
 
-### 4. Start The First Slice
+### 5. Start The First Slice
 
 After the context docs are reviewed:
 

package/README_FOR_AI.md

@@ -8,6 +8,7 @@ Important: slice numbering resets inside each spec. `slice-01` is the first slic
 The canonical installer entrypoint is `npx create-quiver` run from the target project root.
 Do not recommend global installation; use `npx` or a project-local devDependency when the team needs a pinned version.
 The post-init contract is validated with `npx create-quiver doctor --dir <project>`.
+If the project already exists from an older Quiver version, run `npx create-quiver migrate --dir <project>` before `analyze`.
 Maintain release notes and package publishing with `scripts/release-quiver.sh`.
 The primary generated project context for agents is `docs/AI_CONTEXT.md`.
 If a generated project has been analyzed, the exact agent handoff prompt is `docs/AI_ONBOARDING_PROMPT.md`.
@@ -76,15 +77,16 @@ After initialization, the user should:
 3. Fill in `docs/CONTEXTO.md`
 4. Fill in `docs/STATUS.md`
 5. Run `npx create-quiver analyze --dir <project>` if scan artifacts are missing
-6. Ask the AI agent to execute `docs/AI_ONBOARDING_PROMPT.md`
-7. Review context docs before creating the first implementation slice
-8. Open and merge the documentation PR that establishes the workflow files
-9. Create the first slice in `specs/{{PROJECT_SLUG}}/slices/[slice-id]/`
-10. Add `ticket` and `git.*`
-11. Run `tools/scripts/start-slice.sh [--allow-draft] <slice.json>`
-12. Make one commit per slice
-13. Open one PR per spec
-14. Validate the slice and the final PR with the workflow gates
+6. If the project already exists from an older Quiver version, run `npx create-quiver migrate --dir <project>`
+7. Ask the AI agent to execute `docs/AI_ONBOARDING_PROMPT.md`
+8. Review context docs before creating the first implementation slice
+9. Open and merge the documentation PR that establishes the workflow files
+10. Create the first slice in `specs/{{PROJECT_SLUG}}/slices/[slice-id]/`
+11. Add `ticket` and `git.*`
+12. Run `tools/scripts/start-slice.sh [--allow-draft] <slice.json>`
+13. Make one commit per slice
+14. Open one PR per spec
+15. Validate the slice and the final PR with the workflow gates
 
 Bootstrap note: `start-slice.sh` should resolve paths canonically, prefer a local `develop` or `main` base branch before reaching for `origin`, and reject `draft` slices unless `--allow-draft` is passed intentionally.
 

package/docs/AI_CONTEXT.md.template

@@ -35,6 +35,7 @@ This file is the first stop for any AI agent working in this project. It compres
 ```bash
 cd /path/to/project
 npx create-quiver --name "Project Name"
+npx create-quiver migrate --dir .
 npx create-quiver analyze --dir .
 npx create-quiver doctor --dir .
 bash tools/scripts/start-slice.sh <slice.json>

package/docs/WORKFLOW.md.template

@@ -25,7 +25,8 @@ This document is the canonical implementation workflow for the project.
 4. Mark each slice `ready` before execution.
 5. Open and merge the documentation PR before running the first slice bootstrap.
 6. Read the AI context pack, support matrix, and troubleshooting guide before the first slice if the environment is new or uncertain.
-7. If the project was analyzed, read `AI_ONBOARDING_PROMPT.md` before making documentation updates.
+7. If the project already existed before this Quiver version, run `migrate` before `analyze`.
+8. If the project was analyzed, read `AI_ONBOARDING_PROMPT.md` before making documentation updates.
 
 ## Execution
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",
@@ -12,6 +12,7 @@
     "check:pr": "bash tools/scripts/check-pr-readiness.sh",
     "start:slice": "bash tools/scripts/start-slice.sh",
     "cleanup:slice": "bash tools/scripts/cleanup-slice.sh",
+    "migrate": "bash tools/scripts/migrate-project.sh",
     "package:quiver": "bash scripts/package-quiver.sh",
     "smoke:create-quiver": "bash scripts/ci/smoke-create-quiver.sh",
     "release:quiver": "bash scripts/release-quiver.sh"

package/package.template.json

@@ -5,6 +5,7 @@
     "check:slice": "bash tools/scripts/check-slice-readiness.sh",
     "check:pr": "bash tools/scripts/check-pr-readiness.sh",
     "start:slice": "bash tools/scripts/start-slice.sh",
-    "cleanup:slice": "bash tools/scripts/cleanup-slice.sh"
+    "cleanup:slice": "bash tools/scripts/cleanup-slice.sh",
+    "migrate": "bash tools/scripts/migrate-project.sh"
   }
 }

package/scripts/init-docs.sh

@@ -40,6 +40,7 @@ fi
 PROJECT_NAME="$1"
 PROJECT_SLUG=$(echo "$PROJECT_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-')
 CURRENT_DATE=$(date +%Y-%m-%d)
+MIGRATE_MODE="${QUIVER_MIGRATE:-0}"
 DATE_PLUS_7=$(node -e 'const d = new Date(); d.setDate(d.getDate() + 7); const p = (n) => String(n).padStart(2, "0"); console.log(`${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`);')
 DATE_PLUS_30=$(node -e 'const d = new Date(); d.setDate(d.getDate() + 30); const p = (n) => String(n).padStart(2, "0"); console.log(`${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`);')
 DATE_PLUS_35=$(node -e 'const d = new Date(); d.setDate(d.getDate() + 35); const p = (n) => String(n).padStart(2, "0"); console.log(`${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`);')
@@ -76,6 +77,11 @@ copy_template() {
     if [ -f "$src" ]; then
         # Remover .template del nombre si existe
         dest=$(echo "$dest" | sed 's/\.template$//')
+
+        if [ "$MIGRATE_MODE" = "1" ] && [ -f "$dest" ]; then
+            print_info "Saltado: $dest ya existe"
+            return 0
+        fi
         
         # Copiar y reemplazar placeholders
         sed -e "s/{{PROJECT_NAME}}/$PROJECT_NAME/g" \
@@ -101,6 +107,11 @@ copy_template_keep_name() {
     local dest="$2"
 
     if [ -f "$src" ]; then
+        if [ "$MIGRATE_MODE" = "1" ] && [ -f "$dest" ]; then
+            print_info "Saltado: $dest ya existe"
+            return 0
+        fi
+
         sed -e "s/{{PROJECT_NAME}}/$PROJECT_NAME/g" \
             -e "s/{{PROJECT_SLUG}}/$PROJECT_SLUG/g" \
             -e "s/\[project\]/$PROJECT_SLUG/g" \
@@ -157,24 +168,40 @@ copy_template "docs-template/docs/TESTING_GUIDE_FOR_AI.md.template" "docs/TESTIN
 
 # Copiar archivos que no son templates
 if [ -f "docs-template/docs/UI_STANDARDS.md" ]; then
-    cp "docs-template/docs/UI_STANDARDS.md" "docs/UI_STANDARDS.md"
-    print_success "Creado: docs/UI_STANDARDS.md"
+    if [ "$MIGRATE_MODE" = "1" ] && [ -f "docs/UI_STANDARDS.md" ]; then
+        print_info "Saltado: docs/UI_STANDARDS.md ya existe"
+    else
+        cp "docs-template/docs/UI_STANDARDS.md" "docs/UI_STANDARDS.md"
+        print_success "Creado: docs/UI_STANDARDS.md"
+    fi
 fi
 
 if [ -f "docs-template/docs/MOCK_DATA_GUIDE.md" ]; then
-    cp "docs-template/docs/MOCK_DATA_GUIDE.md" "docs/MOCK_DATA_GUIDE.md"
-    print_success "Creado: docs/MOCK_DATA_GUIDE.md"
+    if [ "$MIGRATE_MODE" = "1" ] && [ -f "docs/MOCK_DATA_GUIDE.md" ]; then
+        print_info "Saltado: docs/MOCK_DATA_GUIDE.md ya existe"
+    else
+        cp "docs-template/docs/MOCK_DATA_GUIDE.md" "docs/MOCK_DATA_GUIDE.md"
+        print_success "Creado: docs/MOCK_DATA_GUIDE.md"
+    fi
 fi
 
 # Copiar configuración de IA
 if [ -f "docs-template/docs/ai/PRINCIPLES.md" ]; then
-    cp "docs-template/docs/ai/PRINCIPLES.md" "docs/ai/PRINCIPLES.md"
-    print_success "Creado: docs/ai/PRINCIPLES.md"
+    if [ "$MIGRATE_MODE" = "1" ] && [ -f "docs/ai/PRINCIPLES.md" ]; then
+        print_info "Saltado: docs/ai/PRINCIPLES.md ya existe"
+    else
+        cp "docs-template/docs/ai/PRINCIPLES.md" "docs/ai/PRINCIPLES.md"
+        print_success "Creado: docs/ai/PRINCIPLES.md"
+    fi
 fi
 
 if [ -f "docs-template/docs/ai/RULES.yaml" ]; then
-    cp "docs-template/docs/ai/RULES.yaml" "docs/ai/RULES.yaml"
-    print_success "Creado: docs/ai/RULES.yaml"
+    if [ "$MIGRATE_MODE" = "1" ] && [ -f "docs/ai/RULES.yaml" ]; then
+        print_info "Saltado: docs/ai/RULES.yaml ya existe"
+    else
+        cp "docs-template/docs/ai/RULES.yaml" "docs/ai/RULES.yaml"
+        print_success "Creado: docs/ai/RULES.yaml"
+    fi
 fi
 
 # Copiar template de LESSONS (vacío)
@@ -240,44 +267,123 @@ NODE
 
 sync_package_json
 
+mkdir -p ".quiver"
+node - <<'NODE'
+const fs = require('fs');
+const path = require('path');
+
+const statePath = path.join('.quiver', 'state.json');
+const packageJson = fs.existsSync('package.json') ? JSON.parse(fs.readFileSync('package.json', 'utf8')) : {};
+const currentVersion = process.env.QUIVER_VERSION || packageJson.version || '0.0.0';
+const migrateMode = process.env.QUIVER_MIGRATE === '1';
+const now = new Date().toISOString();
+const projectName = process.env.QUIVER_PROJECT_NAME || packageJson.name || '';
+
+let existing = {};
+if (fs.existsSync(statePath)) {
+  existing = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+}
+
+const nextState = migrateMode
+  ? {
+      ...existing,
+      quiver_version: currentVersion,
+      project_name: projectName || existing.project_name || '',
+      initialized_version: existing.initialized_version ?? null,
+      migrated_version: currentVersion,
+      last_initialized_at: existing.last_initialized_at ?? null,
+      last_migration_at: now,
+      last_analysis_at: existing.last_analysis_at ?? null,
+    }
+  : {
+    ...existing,
+    quiver_version: currentVersion,
+    project_name: projectName || existing.project_name || '',
+      initialized_version: existing.initialized_version || currentVersion,
+      migrated_version: existing.migrated_version ?? null,
+      last_initialized_at: existing.last_initialized_at || now,
+      last_migration_at: existing.last_migration_at ?? null,
+      last_analysis_at: existing.last_analysis_at ?? null,
+    };
+
+fs.writeFileSync(statePath, `${JSON.stringify(nextState, null, 2)}\n`);
+NODE
+
 # Copiar bootstrap de slices a tools/scripts
 if [ -f "docs-template/scripts/start-slice.sh" ]; then
-    cp "docs-template/scripts/start-slice.sh" "tools/scripts/start-slice.sh"
-    chmod +x "tools/scripts/start-slice.sh"
-    print_success "Creado: tools/scripts/start-slice.sh"
+    if [ "$MIGRATE_MODE" = "1" ] && [ -f "tools/scripts/start-slice.sh" ]; then
+        print_info "Saltado: tools/scripts/start-slice.sh ya existe"
+    else
+        cp "docs-template/scripts/start-slice.sh" "tools/scripts/start-slice.sh"
+        chmod +x "tools/scripts/start-slice.sh"
+        print_success "Creado: tools/scripts/start-slice.sh"
+    fi
 fi
 
 if [ -f "docs-template/scripts/refresh-active-slices.sh" ]; then
-    cp "docs-template/scripts/refresh-active-slices.sh" "tools/scripts/refresh-active-slices.sh"
-    chmod +x "tools/scripts/refresh-active-slices.sh"
-    print_success "Creado: tools/scripts/refresh-active-slices.sh"
+    if [ "$MIGRATE_MODE" = "1" ] && [ -f "tools/scripts/refresh-active-slices.sh" ]; then
+        print_info "Saltado: tools/scripts/refresh-active-slices.sh ya existe"
+    else
+        cp "docs-template/scripts/refresh-active-slices.sh" "tools/scripts/refresh-active-slices.sh"
+        chmod +x "tools/scripts/refresh-active-slices.sh"
+        print_success "Creado: tools/scripts/refresh-active-slices.sh"
+    fi
 fi
 
 if [ -f "docs-template/scripts/check-slice-readiness.sh" ]; then
-    cp "docs-template/scripts/check-slice-readiness.sh" "tools/scripts/check-slice-readiness.sh"
-    chmod +x "tools/scripts/check-slice-readiness.sh"
-    print_success "Creado: tools/scripts/check-slice-readiness.sh"
+    if [ "$MIGRATE_MODE" = "1" ] && [ -f "tools/scripts/check-slice-readiness.sh" ]; then
+        print_info "Saltado: tools/scripts/check-slice-readiness.sh ya existe"
+    else
+        cp "docs-template/scripts/check-slice-readiness.sh" "tools/scripts/check-slice-readiness.sh"
+        chmod +x "tools/scripts/check-slice-readiness.sh"
+        print_success "Creado: tools/scripts/check-slice-readiness.sh"
+    fi
 fi
 
 if [ -f "docs-template/scripts/check-pr-readiness.sh" ]; then
-    cp "docs-template/scripts/check-pr-readiness.sh" "tools/scripts/check-pr-readiness.sh"
-    chmod +x "tools/scripts/check-pr-readiness.sh"
-    print_success "Creado: tools/scripts/check-pr-readiness.sh"
+    if [ "$MIGRATE_MODE" = "1" ] && [ -f "tools/scripts/check-pr-readiness.sh" ]; then
+        print_info "Saltado: tools/scripts/check-pr-readiness.sh ya existe"
+    else
+        cp "docs-template/scripts/check-pr-readiness.sh" "tools/scripts/check-pr-readiness.sh"
+        chmod +x "tools/scripts/check-pr-readiness.sh"
+        print_success "Creado: tools/scripts/check-pr-readiness.sh"
+    fi
 fi
 
 if [ -f "docs-template/scripts/cleanup-slice.sh" ]; then
-    cp "docs-template/scripts/cleanup-slice.sh" "tools/scripts/cleanup-slice.sh"
-    chmod +x "tools/scripts/cleanup-slice.sh"
-    print_success "Creado: tools/scripts/cleanup-slice.sh"
+    if [ "$MIGRATE_MODE" = "1" ] && [ -f "tools/scripts/cleanup-slice.sh" ]; then
+        print_info "Saltado: tools/scripts/cleanup-slice.sh ya existe"
+    else
+        cp "docs-template/scripts/cleanup-slice.sh" "tools/scripts/cleanup-slice.sh"
+        chmod +x "tools/scripts/cleanup-slice.sh"
+        print_success "Creado: tools/scripts/cleanup-slice.sh"
+    fi
 fi
 
 if [ -f "docs-template/scripts/check-scope.sh" ]; then
-    cp "docs-template/scripts/check-scope.sh" "tools/scripts/check-scope.sh"
-    chmod +x "tools/scripts/check-scope.sh"
-    print_success "Creado: tools/scripts/check-scope.sh"
+    if [ "$MIGRATE_MODE" = "1" ] && [ -f "tools/scripts/check-scope.sh" ]; then
+        print_info "Saltado: tools/scripts/check-scope.sh ya existe"
+    else
+        cp "docs-template/scripts/check-scope.sh" "tools/scripts/check-scope.sh"
+        chmod +x "tools/scripts/check-scope.sh"
+        print_success "Creado: tools/scripts/check-scope.sh"
+    fi
+fi
+
+if [ -f "docs-template/scripts/migrate-project.sh" ]; then
+    if [ "$MIGRATE_MODE" = "1" ] && [ -f "tools/scripts/migrate-project.sh" ]; then
+        print_info "Saltado: tools/scripts/migrate-project.sh ya existe"
+    else
+        cp "docs-template/scripts/migrate-project.sh" "tools/scripts/migrate-project.sh"
+        chmod +x "tools/scripts/migrate-project.sh"
+        print_success "Creado: tools/scripts/migrate-project.sh"
+    fi
 fi
 
 # Crear archivo SEARCH.md básico
+if [ "$MIGRATE_MODE" = "1" ] && [ -f "docs/SEARCH.md" ]; then
+    print_info "Saltado: docs/SEARCH.md ya existe"
+else
 cat > "docs/SEARCH.md" << EOF
 # Búsqueda por Tema
 
@@ -319,8 +425,11 @@ cat > "docs/SEARCH.md" << EOF
 
 **Fin de la búsqueda**
 EOF
+fi
 
-print_success "Creado: docs/SEARCH.md"
+if [ "$MIGRATE_MODE" != "1" ] || [ ! -f "docs/SEARCH.md" ]; then
+    print_success "Creado: docs/SEARCH.md"
+fi
 
 # Crear README.md en la raíz del proyecto (si no existe)
 if [ ! -f "README.md" ]; then
@@ -347,6 +456,26 @@ npm install --save-dev create-quiver
 
 If your project path contains spaces, quote it explicitly when using \`--dir\`.
 
+## Upgrading Existing Projects
+
+If the project already existed before this Quiver version, upgrade it from the project root:
+
+\`\`\`bash
+cd /path/to/your-project
+npx create-quiver migrate --dir .
+npx create-quiver analyze --dir .
+npx create-quiver doctor --dir .
+\`\`\`
+
+If your team prefers a pinned local dependency, update the package first and then run the same flow:
+
+\`\`\`bash
+npm install --save-dev create-quiver@latest
+npx create-quiver migrate --dir .
+npx create-quiver analyze --dir .
+npx create-quiver doctor --dir .
+\`\`\`
+
 ## AI Context Onboarding
 
 After analysis and doctor validation, open your AI agent in this project and run:

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

package/src/create-quiver/index.js

@@ -2,6 +2,8 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execFileSync } = require('child_process');
+const cliPackageJson = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../..', 'package.json'), 'utf8'));
+const CLI_VERSION = cliPackageJson.version || '0.0.0';
 
 function formatError(message) {
   return `create-quiver: ${message}`;
@@ -11,6 +13,7 @@ function printUsage() {
   console.log(`Usage:
   npx create-quiver [options]
   npx create-quiver analyze [options]
+  npx create-quiver migrate [options]
   npx create-quiver doctor [options]
 
 Options:
@@ -23,6 +26,7 @@ Examples:
   npx create-quiver --name "My Project"
   npx create-quiver --name "My Project" --dir ./my-project
   npx create-quiver analyze --dir ./my-project
+  npx create-quiver migrate --dir ./my-project
   npx create-quiver doctor --dir ./my-project
   node bin/create-quiver.js doctor --dir ./my-project
 `);
@@ -38,12 +42,15 @@ function parseArgs(argv) {
   };
 
   const args = [...argv];
-  if (args[0] === 'doctor' || args[0] === 'analyze') {
+  if (args[0] === 'doctor' || args[0] === 'analyze' || args[0] === 'migrate') {
     result.mode = args[0];
     args.shift();
   } else if (args[0] === '--analyze') {
     result.mode = 'analyze';
     args.shift();
+  } else if (args[0] === '--migrate') {
+    result.mode = 'migrate';
+    args.shift();
   } else if (args[0] === '--doctor') {
     result.mode = 'doctor';
     args.shift();
@@ -69,6 +76,11 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--migrate') {
+      result.mode = 'migrate';
+      continue;
+    }
+
     if (arg === '-n' || arg === '--name' || arg === '--project-name') {
       const value = args[++index];
       if (!value) {
@@ -177,12 +189,99 @@ function copyTemplate(templateRoot, targetDir) {
   return docsTemplateDir;
 }
 
+function mergeDirectoryTree(sourceDir, targetDir) {
+  if (!fs.existsSync(sourceDir)) {
+    return;
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+  fs.cpSync(sourceDir, targetDir, {
+    recursive: true,
+    force: false,
+    errorOnExist: false,
+    preserveTimestamps: true,
+  });
+}
+
 function runInitDocs(repoRoot, projectName) {
   runCommand('bash', ['docs-template/scripts/init-docs.sh', projectName], {
     cwd: repoRoot,
   });
 }
 
+function runInitDocsWithMode(repoRoot, projectName, mode) {
+  return runCommand('bash', ['docs-template/scripts/init-docs.sh', projectName], {
+    cwd: repoRoot,
+    env: {
+      ...process.env,
+      QUIVER_PROJECT_NAME: projectName,
+      QUIVER_MIGRATE: mode === 'migrate' ? '1' : '0',
+      QUIVER_VERSION: CLI_VERSION,
+    },
+  });
+}
+
+function writeQuiverState(projectRoot, nextState) {
+  const stateDir = path.join(projectRoot, '.quiver');
+  const statePath = path.join(stateDir, 'state.json');
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(statePath, `${JSON.stringify(nextState, null, 2)}\n`);
+  return statePath;
+}
+
+function readQuiverState(projectRoot) {
+  return readJsonIfExists(path.join(projectRoot, '.quiver', 'state.json'));
+}
+
+function createInitialQuiverState(projectName) {
+  const now = new Date().toISOString();
+
+  return {
+    project_name: projectName,
+    quiver_version: CLI_VERSION,
+    initialized_version: CLI_VERSION,
+    migrated_version: null,
+    last_initialized_at: now,
+    last_migration_at: null,
+    last_analysis_at: null,
+  };
+}
+
+function updateQuiverStateForAnalyze(projectRoot) {
+  const currentState = readQuiverState(projectRoot);
+
+  if (!currentState) {
+    return null;
+  }
+
+  const nextState = {
+    ...currentState,
+    quiver_version: CLI_VERSION,
+    last_analysis_at: new Date().toISOString(),
+  };
+
+  writeQuiverState(projectRoot, nextState);
+  return nextState;
+}
+
+function updateQuiverStateForMigrate(projectRoot, projectName) {
+  const currentState = readQuiverState(projectRoot);
+  const now = new Date().toISOString();
+  const nextState = {
+    ...(currentState || {}),
+    project_name: projectName,
+    quiver_version: CLI_VERSION,
+    initialized_version: currentState?.initialized_version ?? null,
+    migrated_version: CLI_VERSION,
+    last_initialized_at: currentState?.last_initialized_at ?? null,
+    last_migration_at: now,
+    last_analysis_at: currentState?.last_analysis_at ?? null,
+  };
+
+  writeQuiverState(projectRoot, nextState);
+  return nextState;
+}
+
 function listGeneratedSpecDirs(projectRoot) {
   const specsDir = path.join(projectRoot, 'specs');
 
@@ -797,6 +896,7 @@ function runAnalyze(targetDir) {
 
   const scan = buildProjectScan(projectRoot);
   const artifacts = writeProjectScanArtifacts(projectRoot, scan);
+  updateQuiverStateForAnalyze(projectRoot);
 
   console.log(`Project analysis completed for ${projectRoot}`);
   console.log(`Wrote ${path.relative(projectRoot, artifacts.jsonPath)}`);
@@ -805,6 +905,38 @@ function runAnalyze(targetDir) {
   console.log(`Detected package manager: ${scan.project.package_manager}`);
 }
 
+function runMigrate(targetDir) {
+  const projectRoot = path.resolve(process.cwd(), targetDir);
+
+  if (!fs.existsSync(projectRoot)) {
+    throw new Error(formatError(`target directory does not exist: ${projectRoot}`));
+  }
+
+  const packageJson = loadPackageJson(projectRoot);
+  const projectName = packageJson.name || path.basename(projectRoot) || 'Quiver Project';
+  const packageRoot = path.resolve(__dirname, '../..');
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-migrate-'));
+
+  try {
+    const templateRoot = packTemplate(packageRoot, tempRoot);
+    mergeDirectoryTree(templateRoot, path.join(projectRoot, 'docs-template'));
+    const migrationOutput = runInitDocsWithMode(projectRoot, projectName, 'migrate');
+    updateQuiverStateForMigrate(projectRoot, projectName);
+
+    if (migrationOutput.trim().length > 0) {
+      process.stdout.write(migrationOutput);
+      if (!migrationOutput.endsWith('\n')) {
+        process.stdout.write('\n');
+      }
+    }
+
+    console.log(`Quiver migration completed for ${projectRoot}`);
+    console.log('Missing workflow files were restored without overwriting existing project files.');
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
 function runDoctor(targetDir) {
   const projectRoot = path.resolve(process.cwd(), targetDir);
 
@@ -852,25 +984,32 @@ function runDoctor(targetDir) {
   const missingFiles = assertFilesExist(projectRoot, requiredFiles);
   const nonExecutableScripts = assertExecutablesExist(projectRoot, requiredExecutables);
   const pkg = loadPackageJson(projectRoot);
-  const requiredScripts = ['check:slice', 'check:pr', 'start:slice', 'cleanup:slice'];
+  const requiredScripts = ['check:slice', 'check:pr', 'start:slice', 'cleanup:slice', 'migrate'];
   const missingScripts = requiredScripts.filter((name) => typeof pkg.scripts?.[name] !== 'string');
   const hasScanArtifacts = fs.existsSync(path.join(projectRoot, 'docs', 'PROJECT_SCAN.json'))
     && fs.existsSync(path.join(projectRoot, 'docs', 'PROJECT_MAP.md'));
-
-  const problems = [
+  const quiverState = readQuiverState(projectRoot);
+  const hasQuiverState = Boolean(quiverState);
+  const stateWarnings = hasQuiverState ? [] : ['missing Quiver state metadata: .quiver/state.json'];
+  const migrationProblems = [
     ...missingFiles.map((file) => `missing file: ${file}`),
     ...nonExecutableScripts.map((file) => `missing executable bit: ${file}`),
     ...missingScripts.map((name) => `missing package.json script: ${name}`),
   ];
 
-  if (problems.length > 0) {
-    throw new Error(formatError(`doctor failed:\n- ${problems.join('\n- ')}`));
+  if (migrationProblems.length > 0) {
+    throw new Error(formatError(`doctor failed:\n- ${migrationProblems.join('\n- ')}\n- Run migration first: npx create-quiver migrate --dir .`));
   }
 
   console.log(`Quiver doctor passed for ${projectRoot}`);
   console.log(`Generated project slug: ${projectSlug}`);
   console.log('Next steps:');
-  if (!hasScanArtifacts) {
+  for (const warning of stateWarnings) {
+    console.log(`- Warning: ${warning}`);
+  }
+  if (!hasQuiverState) {
+    console.log('- Run migration first: npx create-quiver migrate --dir .');
+  } else if (!hasScanArtifacts) {
     console.log('- Analyze the project first: npx create-quiver analyze --dir .');
   } else {
     console.log('- Ask your AI agent: Read docs/AI_ONBOARDING_PROMPT.md and execute it.');
@@ -904,6 +1043,11 @@ async function run(argv) {
     return;
   }
 
+  if (args.mode === 'migrate') {
+    runMigrate(args.targetDir);
+    return;
+  }
+
   if (args.mode === 'doctor') {
     runDoctor(args.targetDir);
     return;