create-quiver 0.4.0 → 0.6.0

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

@@ -0,0 +1,26 @@
+# Quiver v0.8 Spec Status
+
+**Spec:** quiver-v08-agent-onboarding-analysis
+**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 | Project Scan Command | Completed | - | 4 | 4 |
+| slice-02 | AI Onboarding Prompt | Completed | - | 3 | 3 |
+| slice-03 | Doctor and README Adoption Flow | Completed | - | 2 | 2 |
+
+## Progress
+
+- Completed slices: 3 / 3
+- Estimated hours: 9
+- Actual hours: 9
+
+## Blockers
+
+| Slice | Blocker | Since | Action needed |
+|-------|---------|-------|---------------|
+| - | - | - | - |

package/specs/quiver-v08-agent-onboarding-analysis/slices/slice-01-project-scan-command/slice.json

@@ -0,0 +1,73 @@
+{
+  "slice_id": "slice-01-project-scan-command",
+  "ticket": "QUIVER-01",
+  "type": "feature",
+  "title": "Project Scan Command",
+  "objective": "Add a deterministic `create-quiver analyze --dir <project>` command that scans an existing project and writes safe onboarding artifacts for humans and AI agents.",
+  "description": "Quiver currently initializes templates and validates them, but it does not inspect the target repository. This slice adds a local analyzer that detects project structure, package metadata, scripts, common frameworks, CI files, docs, and configuration signals without calling an AI provider or exposing secrets.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "project-scan-command",
+    "branch_name": "feature/QUIVER-01-project-scan-command"
+  },
+  "must": [
+    "Add an `analyze` mode to the `create-quiver` CLI with `--dir <project>` support",
+    "Scan common project metadata files such as `package.json`, lockfiles, `pyproject.toml`, `go.mod`, `composer.json`, framework config files, README files, and GitHub workflows when present",
+    "Detect likely stack, package manager, scripts, test/build/dev commands, CI signals, documentation entry points, and top-level source directories",
+    "Write `docs/PROJECT_SCAN.json` with structured scan data and `docs/PROJECT_MAP.md` with a readable summary",
+    "Ignore heavy or generated folders including `.git`, `node_modules`, `dist`, `build`, `.next`, `coverage`, and vendor caches",
+    "Never read or serialize secret values from `.env`, `.env.*`, npm tokens, SSH keys, or private credential files"
+  ],
+  "not_included": [
+    "Calling an AI model or generating natural-language conclusions beyond deterministic summaries",
+    "Editing product source code in the target project",
+    "Running install, build, test, or migration commands in the target project",
+    "Deep dependency vulnerability auditing",
+    "Windows-specific command copy UX beyond portable path generation"
+  ],
+  "acceptance": [
+    "`npx create-quiver analyze --dir .` completes in a project that already has Quiver docs",
+    "The command creates or updates `docs/PROJECT_SCAN.json` and `docs/PROJECT_MAP.md`",
+    "The JSON artifact is valid JSON and has stable top-level keys for project, stack, commands, structure, ci, docs, risks, and skipped_paths",
+    "The markdown artifact is readable and includes detected commands without inventing missing scripts",
+    "The analyzer reports skipped secret files without printing their contents",
+    "Existing `init` and `doctor` modes continue to work"
+  ],
+  "files": [
+    "src/create-quiver/index.js",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/package-quiver.sh",
+    "specs/quiver-v08-agent-onboarding-analysis/SPEC.md",
+    "specs/quiver-v08-agent-onboarding-analysis/STATUS.md",
+    "specs/quiver-v08-agent-onboarding-analysis/EVIDENCE_REPORT.md",
+    "specs/quiver-v08-agent-onboarding-analysis/slices/slice-01-project-scan-command/slice.json"
+  ],
+  "tests": [
+    "node src/create-quiver/index.js analyze --dir <fixture>",
+    "node src/create-quiver/index.js doctor --dir <fixture>",
+    "bash scripts/ci/smoke-create-quiver.sh",
+    "bash scripts/package-quiver.sh",
+    "JSON parse check for generated `docs/PROJECT_SCAN.json`"
+  ],
+  "documentation": [
+    "specs/quiver-v08-agent-onboarding-analysis/SPEC.md",
+    "specs/quiver-v08-agent-onboarding-analysis/STATUS.md",
+    "specs/quiver-v08-agent-onboarding-analysis/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "quiver-v07-ai-context-pack"
+  ],
+  "assumptions": [
+    "The analyzer should be deterministic and provider-neutral",
+    "The target project already has or can receive a `docs/` directory generated by Quiver",
+    "Project analysis should optimize for onboarding signal, not exhaustive static analysis"
+  ],
+  "estimated_hours": 4,
+  "actual_hours": 0,
+  "status": "draft",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": null
+}

package/specs/quiver-v08-agent-onboarding-analysis/slices/slice-02-ai-onboarding-prompt/slice.json

@@ -0,0 +1,82 @@
+{
+  "slice_id": "slice-02-ai-onboarding-prompt",
+  "ticket": "QUIVER-02",
+  "type": "docs",
+  "title": "AI Onboarding Prompt",
+  "objective": "Generate an exact provider-neutral prompt that instructs an AI agent how to use Quiver scan artifacts and complete project context docs safely.",
+  "description": "The README should not carry a long prompt, but every generated project should include a precise onboarding prompt that can be pasted into Codex, ChatGPT, Claude, or another agent. This slice adds that prompt as a generated artifact tied to the analysis output.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "ai-onboarding-prompt",
+    "branch_name": "docs/QUIVER-02-ai-onboarding-prompt"
+  },
+  "must": [
+    "Add a generated `docs/AI_ONBOARDING_PROMPT.md` artifact or template",
+    "Make the prompt instruct the AI agent to read `docs/AI_CONTEXT.md`, `docs/PROJECT_SCAN.json`, `docs/PROJECT_MAP.md`, `docs/CONTEXTO.md`, `docs/WORKFLOW.md`, and the initial spec before editing",
+    "Constrain the prompt to documentation/context updates only unless the user explicitly authorizes product-code changes",
+    "Tell the AI agent not to read or expose secrets and to record uncertainty instead of inventing facts",
+    "Tell the AI agent to complete `docs/AI_CONTEXT.md`, `docs/CONTEXTO.md`, `docs/STATUS.md`, and the initial onboarding spec where applicable",
+    "Keep the root README concise and point to the generated prompt instead of embedding a long prompt inline"
+  ],
+  "not_included": [
+    "Provider-specific prompt variants",
+    "Automatic prompt execution from the CLI",
+    "A chat UI or hosted onboarding flow",
+    "Replacing the human review step for generated documentation",
+    "Changing the one-spec-one-PR workflow"
+  ],
+  "acceptance": [
+    "A generated project contains `docs/AI_ONBOARDING_PROMPT.md` after the onboarding flow",
+    "The prompt references the analyzer outputs from slice-01",
+    "The prompt has explicit tasks, constraints, validation requirements, and expected final report format",
+    "The prompt prevents product-code changes during onboarding unless explicitly authorized",
+    "The prompt instructs the AI agent to preserve Quiver workflow invariants",
+    "Installer/package smokes fail if the prompt artifact is missing"
+  ],
+  "files": [
+    "docs/AI_ONBOARDING_PROMPT.md.template",
+    "src/create-quiver/index.js",
+    "scripts/init-docs.sh",
+    "scripts/ci/smoke-init-docs.sh",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/package-quiver.sh",
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/INDEX.md.template",
+    "docs/WORKFLOW.md.template",
+    "specs/quiver-v08-agent-onboarding-analysis/STATUS.md",
+    "specs/quiver-v08-agent-onboarding-analysis/EVIDENCE_REPORT.md",
+    "specs/quiver-v08-agent-onboarding-analysis/slices/slice-02-ai-onboarding-prompt/slice.json"
+  ],
+  "tests": [
+    "bash scripts/ci/smoke-init-docs.sh",
+    "bash scripts/ci/smoke-create-quiver.sh",
+    "bash scripts/package-quiver.sh",
+    "Generated prompt content check for required read order and safety constraints"
+  ],
+  "documentation": [
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/INDEX.md.template",
+    "docs/WORKFLOW.md.template",
+    "specs/quiver-v08-agent-onboarding-analysis/STATUS.md",
+    "specs/quiver-v08-agent-onboarding-analysis/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "slice-01-project-scan-command",
+    "quiver-v07-ai-context-pack"
+  ],
+  "assumptions": [
+    "The prompt is more useful as a generated project file than as a long README block",
+    "The analyzer output is available before the AI prompt is run",
+    "The AI agent should fill context docs but the human owner remains responsible for review"
+  ],
+  "estimated_hours": 3,
+  "actual_hours": 0,
+  "status": "draft",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": null
+}

package/specs/quiver-v08-agent-onboarding-analysis/slices/slice-03-doctor-readme-adoption-flow/slice.json

@@ -0,0 +1,76 @@
+{
+  "slice_id": "slice-03-doctor-readme-adoption-flow",
+  "ticket": "QUIVER-03",
+  "type": "docs",
+  "title": "Doctor and README Adoption Flow",
+  "objective": "Update Quiver's public onboarding guidance so users know exactly what to run after installation and do not confuse explanatory labels with shell commands.",
+  "description": "Current doctor output and README guidance validate generated files, but the post-install adoption path is not explicit enough. This slice updates user-facing guidance around init, analyze, doctor, and AI onboarding while keeping commands copy-paste safe.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "doctor-readme-adoption-flow",
+    "branch_name": "docs/QUIVER-03-doctor-readme-adoption-flow"
+  },
+  "must": [
+    "Update `doctor` next steps to show copy-pasteable commands without prefixing them with words like `Run`",
+    "Make `doctor` recommend `create-quiver analyze --dir .` when scan artifacts are missing",
+    "Update README quick start with the recommended sequence: init, analyze, doctor, run generated AI prompt",
+    "Update README_FOR_AI with the exact agent onboarding responsibility and generated prompt location",
+    "Mention path quoting guidance for directories with spaces where commands include absolute paths",
+    "Keep the README concise and avoid embedding the full long prompt inline"
+  ],
+  "not_included": [
+    "Reworking Windows shell support in this slice",
+    "Changing release publishing scripts",
+    "Adding AI-provider integrations",
+    "Changing project template semantics beyond onboarding guidance",
+    "Renaming existing Quiver commands"
+  ],
+  "acceptance": [
+    "`create-quiver doctor` output is understandable as guidance and not mistaken for a command containing `Run`",
+    "README quick start documents the full adoption path from package install to AI onboarding",
+    "README_FOR_AI points agents to `docs/AI_ONBOARDING_PROMPT.md` after analysis",
+    "Smoke tests assert the expected onboarding artifacts and doctor guidance exist",
+    "Existing init, doctor, and package workflows still pass",
+    "The release notes/evidence report record the final user-facing onboarding flow"
+  ],
+  "files": [
+    "README.md",
+    "README_FOR_AI.md",
+    "src/create-quiver/index.js",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/package-quiver.sh",
+    "specs/quiver-v08-agent-onboarding-analysis/STATUS.md",
+    "specs/quiver-v08-agent-onboarding-analysis/EVIDENCE_REPORT.md",
+    "specs/quiver-v08-agent-onboarding-analysis/slices/slice-03-doctor-readme-adoption-flow/slice.json"
+  ],
+  "tests": [
+    "node src/create-quiver/index.js doctor --dir <fixture>",
+    "bash scripts/ci/smoke-create-quiver.sh",
+    "bash scripts/package-quiver.sh",
+    "README command snippet check",
+    "git diff --check"
+  ],
+  "documentation": [
+    "README.md",
+    "README_FOR_AI.md",
+    "specs/quiver-v08-agent-onboarding-analysis/STATUS.md",
+    "specs/quiver-v08-agent-onboarding-analysis/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "slice-01-project-scan-command",
+    "slice-02-ai-onboarding-prompt"
+  ],
+  "assumptions": [
+    "The main adoption problem is unclear sequence, not missing package installation mechanics",
+    "Doctor should guide next steps but should not run analysis automatically without user intent",
+    "Long onboarding instructions belong in generated docs, not in the root README"
+  ],
+  "estimated_hours": 2,
+  "actual_hours": 0,
+  "status": "draft",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": null
+}

package/specs/quiver-v09-onboarding-readme-flow/EVIDENCE_REPORT.md

@@ -0,0 +1,33 @@
+# Quiver v0.9 Evidence Report
+
+**Spec:** quiver-v09-onboarding-readme-flow
+**Last updated:** 2026-04-21
+**Status:** Completed
+
+## Summary
+
+| Slice | Acceptance criteria | Status | Evidence |
+|-------|---------------------|--------|----------|
+| slice-01 | 5 | Completed | `bash scripts/ci/smoke-init-docs.sh` |
+| slice-02 | 5 | Completed | `bash scripts/ci/smoke-create-quiver.sh`, `bash scripts/package-quiver.sh` |
+
+## Evidence by Slice
+
+### slice-01-developer-readme-onboarding-flow
+
+- Reworked the root README around install, analyze, doctor, AI handoff, review, and first-slice execution
+- Updated the generated project README in `scripts/init-docs.sh` with the same onboarding path
+- Added smoke assertions for the generated README AI handoff and context review checklist
+- Verified shell syntax with `bash -n scripts/init-docs.sh scripts/ci/smoke-init-docs.sh`
+- Verified generated README behavior with `bash scripts/ci/smoke-init-docs.sh`
+
+### slice-02-ai-handoff-doctor-guidance
+
+- Updated `doctor` to require the AI context and onboarding prompt files
+- Made `doctor` point to `docs/AI_ONBOARDING_PROMPT.md` after scan artifacts exist
+- Updated `README_FOR_AI.md` so agents treat onboarding as context preparation before product work
+- Extended `smoke-create-quiver.sh` to assert the new doctor handoff guidance for local 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 scripts/package-quiver.sh`
+- Verified end-to-end CLI behavior with `bash scripts/ci/smoke-create-quiver.sh`
+- Verified package contract with `bash scripts/package-quiver.sh`

package/specs/quiver-v09-onboarding-readme-flow/SPEC.md

@@ -0,0 +1,44 @@
+# Quiver v0.9 - Onboarding README Flow
+
+**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 README and generated onboarding docs explain the full developer and AI onboarding path so a new project can prepare context before the first implementation slice.
+
+## Scope
+
+### Included
+
+- Reorder the root README around the developer onboarding flow
+- Update the generated project README so it explains analysis, AI context preparation, and review before slices
+- Make the AI handoff explicit without embedding the full prompt in the README
+- Update `doctor` and AI guidance so the CLI points users to the generated prompt after analysis
+- Extend smoke checks so README onboarding guidance and doctor output stay covered
+
+### Excluded
+
+- Changing the analyzer behavior
+- Adding provider-specific AI integrations
+- Changing release publishing behavior
+- Reworking Windows-specific shell support
+- Changing the one-slice-one-commit and one-spec-one-PR rules
+
+## Slices
+
+| Slice | Title | Status | Spec |
+|-------|-------|--------|------|
+| 01 | Developer README Onboarding Flow | Completed | [slice-01](./slices/slice-01-developer-readme-onboarding-flow/slice.json) |
+| 02 | AI Handoff and Doctor Guidance | Completed | [slice-02-ai-handoff-doctor-guidance/slice.json](./slices/slice-02-ai-handoff-doctor-guidance/slice.json) |
+
+## Definition of Done
+
+- The root README shows the full install, analyze, doctor, AI handoff, review, and first-slice flow
+- The generated project README gives the same operational onboarding path
+- The README tells the developer exactly what to ask the AI agent to do
+- `doctor` points to the generated onboarding prompt once the project has scan artifacts
+- Smoke tests cover the README and doctor onboarding guidance
+- The spec is completed with one commit per slice and one PR for the spec

package/specs/quiver-v09-onboarding-readme-flow/STATUS.md

@@ -0,0 +1,25 @@
+# Quiver v0.9 Spec Status
+
+**Spec:** quiver-v09-onboarding-readme-flow
+**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 | Developer README Onboarding Flow | Completed | - | 2 | 2 |
+| slice-02 | AI Handoff and Doctor Guidance | Completed | - | 2 | 2 |
+
+## Progress
+
+- Completed slices: 2 / 2
+- Estimated hours: 4
+- Actual hours: 4
+
+## Blockers
+
+| Slice | Blocker | Since | Action needed |
+|-------|---------|-------|---------------|
+| - | - | - | - |

package/specs/quiver-v09-onboarding-readme-flow/slices/slice-01-developer-readme-onboarding-flow/slice.json

@@ -0,0 +1,69 @@
+{
+  "slice_id": "slice-01-developer-readme-onboarding-flow",
+  "ticket": "QUIVER-01",
+  "type": "docs",
+  "title": "Developer README Onboarding Flow",
+  "objective": "Rework the root README and generated project README so developers understand the full Quiver onboarding path before creating implementation slices.",
+  "description": "The current README has the required commands, but it does not clearly separate installation, project analysis, AI context preparation, human review, and first slice execution. This slice turns the README into an operational onboarding guide for developers.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "onboarding-readme-flow",
+    "branch_name": "docs/QUIVER-09-onboarding-readme-flow"
+  },
+  "must": [
+    "Rewrite the root README quick start into a developer onboarding flow",
+    "Explain what `create-quiver analyze --dir .` generates and why it exists",
+    "Add the exact short instruction developers should give the AI agent after analysis",
+    "Move the first-slice workflow after context preparation and human review",
+    "Update the generated project README created by `scripts/init-docs.sh` with the same flow"
+  ],
+  "not_included": [
+    "Changing `doctor` output",
+    "Changing `README_FOR_AI.md`",
+    "Adding AI-provider integrations",
+    "Changing analyzer behavior"
+  ],
+  "acceptance": [
+    "The root README describes install, analyze, doctor, AI handoff, review, and first slice in order",
+    "The generated project README tells the developer how to prepare AI context before starting a slice",
+    "The README does not embed the full long onboarding prompt",
+    "The generated README links to `docs/AI_ONBOARDING_PROMPT.md`",
+    "`bash scripts/ci/smoke-init-docs.sh` passes"
+  ],
+  "files": [
+    "README.md",
+    "scripts/init-docs.sh",
+    "scripts/ci/smoke-init-docs.sh",
+    "specs/quiver-v09-onboarding-readme-flow/SPEC.md",
+    "specs/quiver-v09-onboarding-readme-flow/STATUS.md",
+    "specs/quiver-v09-onboarding-readme-flow/EVIDENCE_REPORT.md",
+    "specs/quiver-v09-onboarding-readme-flow/slices/slice-01-developer-readme-onboarding-flow/slice.json"
+  ],
+  "tests": [
+    "bash -n scripts/init-docs.sh scripts/ci/smoke-init-docs.sh",
+    "bash scripts/ci/smoke-init-docs.sh",
+    "git diff --check"
+  ],
+  "documentation": [
+    "README.md",
+    "specs/quiver-v09-onboarding-readme-flow/SPEC.md",
+    "specs/quiver-v09-onboarding-readme-flow/STATUS.md",
+    "specs/quiver-v09-onboarding-readme-flow/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "quiver-v08-agent-onboarding-analysis"
+  ],
+  "assumptions": [
+    "The README should remain concise and point to the generated prompt instead of duplicating it",
+    "The developer owns review and approval of AI-generated context docs",
+    "Context preparation should happen before first slice execution"
+  ],
+  "estimated_hours": 2,
+  "actual_hours": 2,
+  "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-v09-onboarding-readme-flow/slices/slice-02-ai-handoff-doctor-guidance/slice.json

@@ -0,0 +1,71 @@
+{
+  "slice_id": "slice-02-ai-handoff-doctor-guidance",
+  "ticket": "QUIVER-02",
+  "type": "docs",
+  "title": "AI Handoff and Doctor Guidance",
+  "objective": "Align AI-facing guidance and doctor output with the README onboarding flow so the CLI tells users when to run the generated prompt.",
+  "description": "Once README onboarding is clear, the CLI and AI guide should reinforce the same handoff: analyze the project, validate the generated contract, then ask the AI agent to execute `docs/AI_ONBOARDING_PROMPT.md` before creating slices.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "onboarding-readme-flow",
+    "branch_name": "docs/QUIVER-09-onboarding-readme-flow"
+  },
+  "must": [
+    "Update `doctor` output to point to `docs/AI_ONBOARDING_PROMPT.md` after scan artifacts exist",
+    "Update `README_FOR_AI.md` so agents understand onboarding means preparing context before feature work",
+    "Extend create-quiver smoke coverage for the new doctor handoff guidance",
+    "Run package smoke to confirm the published template still includes the onboarding artifacts",
+    "Close the spec evidence and status files"
+  ],
+  "not_included": [
+    "Changing generated prompt content beyond references needed for consistency",
+    "Changing analyzer output shape",
+    "Changing release publishing behavior",
+    "Opening multiple PRs for this spec"
+  ],
+  "acceptance": [
+    "After `analyze`, `doctor` tells the developer to run `docs/AI_ONBOARDING_PROMPT.md` with their AI agent",
+    "`README_FOR_AI.md` says the initial AI job is context preparation, not product implementation",
+    "Smoke tests verify the new doctor output",
+    "Package smoke still passes",
+    "The spec status and evidence show both slices completed"
+  ],
+  "files": [
+    "README_FOR_AI.md",
+    "src/create-quiver/index.js",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/package-quiver.sh",
+    "specs/quiver-v09-onboarding-readme-flow/SPEC.md",
+    "specs/quiver-v09-onboarding-readme-flow/STATUS.md",
+    "specs/quiver-v09-onboarding-readme-flow/EVIDENCE_REPORT.md",
+    "specs/quiver-v09-onboarding-readme-flow/slices/slice-02-ai-handoff-doctor-guidance/slice.json"
+  ],
+  "tests": [
+    "node -c src/create-quiver/index.js",
+    "bash scripts/ci/smoke-create-quiver.sh",
+    "bash scripts/package-quiver.sh",
+    "git diff --check"
+  ],
+  "documentation": [
+    "README_FOR_AI.md",
+    "specs/quiver-v09-onboarding-readme-flow/SPEC.md",
+    "specs/quiver-v09-onboarding-readme-flow/STATUS.md",
+    "specs/quiver-v09-onboarding-readme-flow/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "slice-01-developer-readme-onboarding-flow"
+  ],
+  "assumptions": [
+    "Doctor should guide next steps but not execute the AI prompt automatically",
+    "The generated prompt remains provider-neutral",
+    "The same branch can hold both slice commits for one spec PR"
+  ],
+  "estimated_hours": 2,
+  "actual_hours": 2,
+  "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-v10-local-project-installation-guidance/EVIDENCE_REPORT.md

@@ -0,0 +1,25 @@
+# Quiver v0.10 Evidence Report
+
+**Spec:** quiver-v10-local-project-installation-guidance
+**Last updated:** 2026-04-21
+**Status:** Completed
+
+## Summary
+
+| Slice | Acceptance criteria | Status | Evidence |
+|-------|---------------------|--------|----------|
+| slice-01 | 5 | Completed | `bash scripts/ci/smoke-init-docs.sh`, `bash scripts/ci/smoke-create-quiver.sh` |
+
+## Evidence by Slice
+
+### slice-01-local-project-installation-guidance
+
+- Updated the root README to prioritize running Quiver from the target project root with `npx`
+- Documented project-local pinned installation with `npm install --save-dev create-quiver`
+- Explicitly discouraged global installation
+- Updated generated README guidance in `scripts/init-docs.sh`
+- Updated AI-facing guidance in `README_FOR_AI.md` and `docs/AI_CONTEXT.md.template`
+- Added smoke assertions for generated README guidance
+- Verified shell syntax with `bash -n scripts/init-docs.sh scripts/ci/smoke-init-docs.sh scripts/ci/smoke-create-quiver.sh`
+- Verified generated docs with `bash scripts/ci/smoke-init-docs.sh`
+- Verified CLI smoke with `bash scripts/ci/smoke-create-quiver.sh`

package/specs/quiver-v10-local-project-installation-guidance/SPEC.md

@@ -0,0 +1,42 @@
+# Quiver v0.10 - Local Project Installation Guidance
+
+**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
+
+Clarify that Quiver should be run from the project where the workflow will live, preferably through `npx`, and should not be installed globally.
+
+## Scope
+
+### Included
+
+- Update the root README to recommend running Quiver from the project root
+- Make `npx create-quiver --name "Project Name"` the primary path
+- Document `npm install --save-dev create-quiver` as the pinned project-local option
+- Explicitly discourage global installation
+- Update generated project README and AI-facing docs with the same guidance
+- Add smoke checks for the new guidance
+
+### Excluded
+
+- CLI behavior changes
+- npm package version changes
+- Release publishing
+- Windows-specific installation changes
+
+## Slices
+
+| Slice | Title | Status | Spec |
+|-------|-------|--------|------|
+| 01 | Local Project Installation Guidance | Completed | [slice-01](./slices/slice-01-local-project-installation-guidance/slice.json) |
+
+## Definition of Done
+
+- The README tells developers to run Quiver from the target project root
+- The README does not recommend global installation
+- The generated project README includes the same local-project guidance
+- AI-facing docs refer to the local project root as the operating context
+- Smoke checks verify the generated README guidance

package/specs/quiver-v10-local-project-installation-guidance/STATUS.md

@@ -0,0 +1,24 @@
+# Quiver v0.10 Spec Status
+
+**Spec:** quiver-v10-local-project-installation-guidance
+**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 | Local Project Installation Guidance | Completed | - | 1 | 1 |
+
+## Progress
+
+- Completed slices: 1 / 1
+- Estimated hours: 1
+- Actual hours: 1
+
+## Blockers
+
+| Slice | Blocker | Since | Action needed |
+|-------|---------|-------|---------------|
+| - | - | - | - |