create-quiver 0.4.0 → 0.5.0

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

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

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