create-quiver 0.4.0 → 0.5.0

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

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