create-quiver 0.4.0 → 0.6.0

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" \
@@ -141,6 +152,8 @@ copy_file_if_missing() {
 
 # Copiar templates de docs/
 copy_template "docs-template/docs/INDEX.md.template" "docs/INDEX.md"
+copy_template "docs-template/docs/AI_CONTEXT.md.template" "docs/AI_CONTEXT.md"
+copy_template "docs-template/docs/AI_ONBOARDING_PROMPT.md.template" "docs/AI_ONBOARDING_PROMPT.md"
 copy_template "docs-template/docs/CONTEXTO.md.template" "docs/CONTEXTO.md"
 copy_template "docs-template/docs/STATUS.md.template" "docs/STATUS.md"
 copy_template "docs-template/docs/WORKFLOW.md.template" "docs/WORKFLOW.md"
@@ -155,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)
@@ -238,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
 
@@ -283,6 +391,14 @@ cat > "docs/SEARCH.md" << EOF
 
 ---
 
+## AI Context
+
+- **Agent context pack:** \`docs/AI_CONTEXT.md\`
+- **Project overview:** \`docs/CONTEXTO.md\`
+- **Workflow:** \`docs/WORKFLOW.md\`
+
+---
+
 ## Autenticación
 
 - **Spec:** \`../specs/$PROJECT_SLUG/slices/slice-01/slice.json\`
@@ -309,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
@@ -321,20 +440,74 @@ if [ ! -f "README.md" ]; then
 
 ## Quick Start
 
+Run Quiver from this project root. Do not install it globally.
+
 \`\`\`bash
 npm install
-cp .env.example .env.local
-npm run dev
+npx create-quiver analyze --dir .
+npx create-quiver doctor --dir .
+\`\`\`
+
+If this project needs a pinned Quiver version, install it as a devDependency:
+
+\`\`\`bash
+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:
+
+\`\`\`text
+Read docs/AI_ONBOARDING_PROMPT.md and execute it.
+Do not modify product code unless I explicitly authorize it.
+Prepare the project context docs and report assumptions, risks, and files changed.
 \`\`\`
 
+Review the AI changes to docs/AI_CONTEXT.md, docs/CONTEXTO.md, docs/STATUS.md, and specs/$PROJECT_SLUG/SPEC.md before starting implementation work.
+
+## First Slice Workflow
+
+1. Review or refine specs/$PROJECT_SLUG/SPEC.md.
+2. Create the first slice from specs/$PROJECT_SLUG/slices/slice-template/slice.json.
+3. Start work with tools/scripts/start-slice.sh <slice.json>.
+4. Make one commit per slice.
+5. Open one PR per spec.
+
 ## Verification Checklist
 
 - [ ] npm install completes
-- [ ] npm run dev starts
-- [ ] App opens at http://localhost:3000
+- [ ] npx create-quiver analyze --dir . completes
+- [ ] npx create-quiver doctor --dir . completes
+- [ ] AI agent executed docs/AI_ONBOARDING_PROMPT.md
+- [ ] Context docs were reviewed before the first slice
 
 ## Documentation
 
+- [AI Context](./docs/AI_CONTEXT.md) - Contexto resumido para IA
+- [AI Onboarding Prompt](./docs/AI_ONBOARDING_PROMPT.md) - Handoff exacto para agentes después del análisis
 - [Contexto](./docs/CONTEXTO.md) - Qué es $PROJECT_NAME
 - [Workflow](./docs/WORKFLOW.md) - Cómo implementar
 - [Support Matrix](./docs/SUPPORT_MATRIX.md) - Qué entornos están soportados
@@ -357,10 +530,11 @@ echo "   docs/archive/            ← Histórico (vacío)"
 echo "   specs/$PROJECT_SLUG/     ← Especificaciones del proyecto"
 echo ""
 echo "📝 Próximos pasos:"
-echo "   1. Editar docs/CONTEXTO.md con la información de tu proyecto"
-echo "   2. Editar docs/STATUS.md con el estado actual"
-echo "   3. Crear el primer directorio de slice en specs/$PROJECT_SLUG/slices/[slice-id]/"
-echo "   4. Actualizar docs/SEARCH.md con temas específicos"
+echo "   1. Editar docs/AI_CONTEXT.md con el contexto resumido para IA"
+echo "   2. Editar docs/CONTEXTO.md con la información de tu proyecto"
+echo "   3. Editar docs/STATUS.md con el estado actual"
+echo "   4. Crear el primer directorio de slice en specs/$PROJECT_SLUG/slices/[slice-id]/"
+echo "   5. Actualizar docs/SEARCH.md con temas específicos"
 echo ""
 echo "📖 Más información:"
 echo "   - Ver docs-template/TEMPLATE.md para guía de personalización"

package/scripts/package-quiver.sh

@@ -58,6 +58,8 @@ required_paths=(
   "package/src/create-quiver/index.js"
   "package/README.md"
   "package/README_FOR_AI.md"
+  "package/docs/AI_CONTEXT.md.template"
+  "package/docs/AI_ONBOARDING_PROMPT.md.template"
   "package/TEMPLATE.md"
   "package/LICENSE"
   "package/CONTRIBUTING.md"

package/specs/quiver-v07-ai-context-pack/EVIDENCE_REPORT.md

@@ -0,0 +1,24 @@
+# Quiver v0.7 Evidence Report
+
+**Spec:** quiver-v07-ai-context-pack
+**Last updated:** 2026-04-21
+
+## Evidence Collected
+
+- `docs/AI_CONTEXT.md.template` added as the generated AI context pack template
+- `README_FOR_AI.md` now points agents at `docs/AI_CONTEXT.md` first
+- `README.md`, `docs/INDEX.md.template`, `docs/DOCUMENTATION_GUIDE.md.template`, and `docs/WORKFLOW.md.template` now surface the AI context pack
+- `scripts/init-docs.sh` now creates `docs/AI_CONTEXT.md` and prints it as the first follow-up step
+- installer and package smoke tests require the new context pack
+
+## Validation
+
+- `bash -n scripts/init-docs.sh scripts/ci/smoke-init-docs.sh scripts/ci/smoke-create-quiver.sh scripts/package-quiver.sh`
+- `git diff --check`
+- JSON parse of `specs/quiver-v07-ai-context-pack/slices/slice-01-ai-context-pack/slice.json`
+- `bash scripts/ci/smoke-init-docs.sh`
+- `bash scripts/ci/smoke-create-quiver.sh`
+
+## Notes
+
+This spec is intentionally narrow: it adds an agent-facing context pack and wires it into bootstrap and documentation, but it does not attempt automatic repository summarization.

package/specs/quiver-v07-ai-context-pack/SPEC.md

@@ -0,0 +1,40 @@
+# Quiver v0.7 - AI Context Pack
+
+**Date:** 2026-04-21
+**Status:** Completed
+
+Slice numbering resets here: this spec starts at `slice-01` and does not continue any previous spec's numbering.
+
+## Objective
+
+Make the generated project expose a first-class AI context pack so new agents can start from a compact project snapshot instead of rereading the whole repository.
+
+## Scope
+
+### Included
+
+- Add a generated `docs/AI_CONTEXT.md` template for new projects
+- Wire `init-docs.sh` so the AI context pack is created during bootstrap
+- Surface the AI context pack in README, documentation index, and workflow docs
+- Update installer and package smokes so the new file is required
+
+### Excluded
+
+- Building a runtime repository analyzer that auto-summarizes arbitrary source code
+- Changing slice execution semantics
+- Changing release publishing behavior
+- Creating a separate AI localization system
+
+## Slices
+
+| Slice | Title | Status |
+|-------|-------|--------|
+| 01 | AI Context Pack Bootstrap | Completed |
+
+## Definition of Done
+
+- New projects generated by `init-docs.sh` include `docs/AI_CONTEXT.md`
+- The AI context pack is linked from the generated documentation index, workflow, and README guidance
+- Installer and package smoke tests fail if the AI context pack is missing
+- The AI context pack clearly tells agents what to read first and which invariants to preserve
+- The implementation stays limited to one slice and does not broaden into runtime analysis

package/specs/quiver-v07-ai-context-pack/STATUS.md

@@ -0,0 +1,24 @@
+# Quiver v0.7 Spec Status
+
+**Spec:** quiver-v07-ai-context-pack
+**Last updated:** 2026-04-21
+
+Slice numbering is local to this spec. The first slice is `slice-01`.
+
+## Status
+
+| Slice | Title | Status | PR | Estimated hours | Actual hours |
+|-------|-------|--------|----|-----------------|--------------|
+| slice-01 | AI Context Pack Bootstrap | Completed | - | 3 | 3 |
+
+## Progress
+
+- Completed slices: 1 / 1
+- Estimated hours: 3
+- Actual hours: 3
+
+## Blockers
+
+| Slice | Blocker | Since | Action needed |
+|-------|---------|-------|---------------|
+| - | - | - | - |

package/specs/quiver-v07-ai-context-pack/slices/slice-01-ai-context-pack/slice.json

@@ -0,0 +1,79 @@
+{
+  "slice_id": "slice-01-ai-context-pack",
+  "ticket": "QUIVER-01",
+  "type": "docs",
+  "title": "AI Context Pack Bootstrap",
+  "objective": "Create a first-class generated AI context pack and wire it into bootstrap, docs, and smokes so new projects expose a compact agent entry point by default.",
+  "description": "New projects currently generate `docs/CONTEXTO.md` as the human project overview, but they do not generate a dedicated AI context pack. That forces agents to infer too much from scattered docs. This slice adds `docs/AI_CONTEXT.md`, updates the generated docs entry points, and ensures the installer and package smokes require the new file.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "develop",
+    "branch_slug": "ai-context-pack",
+    "branch_name": "docs/QUIVER-01-ai-context-pack"
+  },
+  "must": [
+    "Add `docs/AI_CONTEXT.md.template` to the template repo",
+    "Make `scripts/init-docs.sh` create `docs/AI_CONTEXT.md` in generated projects",
+    "Link the AI context pack from the README, docs index, workflow guide, and documentation guide",
+    "Update the installer and package smoke tests so the new context pack is required",
+    "Keep the change limited to a single slice and do not implement runtime summarization"
+  ],
+  "not_included": [
+    "Automatic source-code analysis that derives a repository summary at runtime",
+    "Changes to slice execution semantics",
+    "Release publishing changes",
+    "Localization beyond the existing generated docs"
+  ],
+  "acceptance": [
+    "A fresh project generated by `init-docs.sh` contains `docs/AI_CONTEXT.md`",
+    "The generated docs index and workflow link to the AI context pack",
+    "The root README tells agents to read the AI context pack first in generated projects",
+    "Package and installer smokes fail if the AI context pack template is missing",
+    "The AI context pack explains the project contract, read order, and core invariants"
+  ],
+  "files": [
+    "docs/AI_CONTEXT.md.template",
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/INDEX.md.template",
+    "docs/DOCUMENTATION_GUIDE.md.template",
+    "docs/WORKFLOW.md.template",
+    "docs/CONTEXTO.md.template",
+    "scripts/init-docs.sh",
+    "scripts/ci/smoke-init-docs.sh",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/package-quiver.sh",
+    "specs/quiver-v07-ai-context-pack/SPEC.md",
+    "specs/quiver-v07-ai-context-pack/STATUS.md",
+    "specs/quiver-v07-ai-context-pack/EVIDENCE_REPORT.md",
+    "specs/quiver-v07-ai-context-pack/slices/slice-01-ai-context-pack/slice.json"
+  ],
+  "tests": [
+    "init-docs smoke",
+    "package smoke",
+    "installer smoke",
+    "README and workflow link checks",
+    "git diff whitespace check"
+  ],
+  "documentation": [
+    "specs/quiver-v07-ai-context-pack/SPEC.md",
+    "specs/quiver-v07-ai-context-pack/STATUS.md",
+    "specs/quiver-v07-ai-context-pack/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "quiver-v05-readme-adoption-contract",
+    "quiver-v06-release-readiness"
+  ],
+  "assumptions": [
+    "The AI context pack should remain a generated doc, not a runtime analyzer",
+    "The generated context pack should complement, not replace, `docs/CONTEXTO.md`",
+    "The project keeps its existing slice workflow and release helpers"
+  ],
+  "estimated_hours": 3,
+  "actual_hours": 3,
+  "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-v08-agent-onboarding-analysis/EVIDENCE_REPORT.md

@@ -0,0 +1,49 @@
+# Quiver v0.8 Evidence Report
+
+**Spec:** quiver-v08-agent-onboarding-analysis
+**Last updated:** 2026-04-21
+**Status:** Completed
+
+## Summary
+
+| Slice | Acceptance criteria | Status | Evidence |
+|-------|---------------------|--------|----------|
+| slice-01 | 6 | Completed | `bash scripts/ci/smoke-create-quiver.sh`, `node -c src/create-quiver/index.js`, `bash -n scripts/ci/smoke-create-quiver.sh` |
+| slice-02 | 6 | Completed | `bash scripts/ci/smoke-init-docs.sh`, `bash scripts/ci/smoke-create-quiver.sh`, `bash scripts/package-quiver.sh` |
+| slice-03 | 6 | Completed | `bash scripts/ci/smoke-init-docs.sh`, `bash scripts/ci/smoke-create-quiver.sh`, `bash scripts/package-quiver.sh`, `git diff --check` |
+
+## Evidence by Slice
+
+### slice-01-project-scan-command
+
+- Added `create-quiver analyze --dir <project>` support in `src/create-quiver/index.js`
+- Generated `docs/PROJECT_SCAN.json` and `docs/PROJECT_MAP.md` from a local repository scan
+- Extended the smoke test to run `analyze` on fresh, existing, and packaged installs
+- Verified syntax with `node -c src/create-quiver/index.js`
+- Verified shell syntax with `bash -n scripts/ci/smoke-create-quiver.sh`
+- Verified end-to-end behavior with `bash scripts/ci/smoke-create-quiver.sh`
+
+### slice-02-ai-onboarding-prompt
+
+- Added `docs/AI_ONBOARDING_PROMPT.md.template` to the packaged docs templates
+- Wired `scripts/init-docs.sh` to generate `docs/AI_ONBOARDING_PROMPT.md`
+- Updated the AI guide and generated docs templates to link the onboarding prompt
+- Extended init, create, and package smokes to require and validate the prompt artifact
+- Verified shell syntax with `bash -n scripts/init-docs.sh scripts/ci/smoke-init-docs.sh scripts/ci/smoke-create-quiver.sh scripts/package-quiver.sh`
+- Verified `docs/AI_ONBOARDING_PROMPT.md` generation with `bash scripts/ci/smoke-init-docs.sh`
+- Verified end-to-end behavior with `bash scripts/ci/smoke-create-quiver.sh`
+- Verified package inclusion with `bash scripts/package-quiver.sh`
+
+### slice-03-doctor-readme-adoption-flow
+
+- Updated `doctor` to print copy-pasteable commands without the confusing `Run` prefix
+- Made `doctor` recommend `npx create-quiver analyze --dir .` when scan artifacts are missing
+- Updated the root README and generated bootstrap README to describe the full adopt-analyze-doctor-prompt flow
+- Added quoting guidance for paths that contain spaces
+- Extended the smoke tests to verify the new doctor guidance and README onboarding sequence
+- Verified shell syntax with `bash -n scripts/init-docs.sh scripts/ci/smoke-init-docs.sh scripts/ci/smoke-create-quiver.sh scripts/package-quiver.sh`
+- Verified syntax with `node -c src/create-quiver/index.js`
+- Verified end-to-end behavior with `bash scripts/ci/smoke-init-docs.sh`
+- Verified end-to-end behavior with `bash scripts/ci/smoke-create-quiver.sh`
+- Verified package inclusion with `bash scripts/package-quiver.sh`
+- Verified the final diff stays clean with `git diff --check`

package/specs/quiver-v08-agent-onboarding-analysis/SPEC.md

@@ -0,0 +1,53 @@
+# Quiver v0.8 - Agent Onboarding Analysis
+
+**Date:** 2026-04-21
+**Status:** Completed
+
+Slice numbering resets here: this spec starts at `slice-01` and does not continue any previous spec's numbering.
+
+## Objective
+
+Make Quiver adoption plug-and-play after installation by adding a deterministic local analysis step that helps an AI agent understand an existing project and fill the generated context docs without guessing.
+
+## Scope
+
+### Included
+
+- Add a local `create-quiver analyze --dir <project>` command that scans a project without calling an AI provider
+- Generate a structured scan artifact and human-readable project map for AI onboarding
+- Generate an exact AI onboarding prompt that tells an agent how to complete Quiver context docs safely
+- Update README, doctor output, and smoke tests so the recommended onboarding flow is install, analyze, validate, then run the prompt with an AI agent
+- Preserve Quiver's existing workflow rules: one commit per slice and one PR per spec
+
+### Excluded
+
+- Calling OpenAI, Claude, or any other AI provider from the CLI
+- Reading or exposing secrets from `.env` files or private local configuration
+- Making product-code changes in the target project during analysis
+- Replacing `docs/AI_CONTEXT.md`, `docs/CONTEXTO.md`, or the existing spec/slice workflow
+- Windows-specific shell UX fixes beyond using portable Node.js path handling in the analyzer
+
+## Proposed Onboarding Flow
+
+1. Install or run Quiver in an existing project.
+2. Run `npx create-quiver analyze --dir .`.
+3. Run `npx create-quiver doctor --dir .`.
+4. Open the AI agent and run the generated prompt from `docs/AI_ONBOARDING_PROMPT.md`.
+5. Review the documentation-only changes and create the first Quiver onboarding PR.
+
+## Slices
+
+| Slice | Title | Status | Spec |
+|-------|-------|--------|------|
+| 01 | Project Scan Command | Completed | [slice-01](./slices/slice-01-project-scan-command/slice.json) |
+| 02 | AI Onboarding Prompt | Completed | [slice-02-ai-onboarding-prompt/slice.json](./slices/slice-02-ai-onboarding-prompt/slice.json) |
+| 03 | Doctor and README Adoption Flow | Completed | [slice-03-doctor-readme-adoption-flow/slice.json](./slices/slice-03-doctor-readme-adoption-flow/slice.json) |
+
+## Definition of Done
+
+- `create-quiver analyze --dir .` creates safe onboarding artifacts in a generated project
+- The analyzer ignores heavy/generated folders and never reads real secret files
+- Generated artifacts give an AI agent enough project structure to fill Quiver context docs
+- README and doctor output expose the exact post-install flow and do not imply that "Run" is part of a command
+- Smoke tests prove the installer/package includes the analyzer and generated onboarding prompt
+- All slices are completed with one commit per slice and one PR for this spec