create-quiver 0.6.0 → 0.7.0

package/specs/quiver-v12-cross-platform-native-runtime/slices/slice-02-node-init-docs-runtime/slice.json

@@ -0,0 +1,76 @@
+{
+  "slice_id": "slice-02-node-init-docs-runtime",
+  "ticket": "QUIVER-02",
+  "type": "feature",
+  "title": "Node Init Docs Runtime",
+  "objective": "Replace the Bash dependency in project initialization with a Node.js implementation.",
+  "description": "The current installer invokes `bash docs-template/scripts/init-docs.sh`, which blocks native Windows usage at the first command. This slice ports initialization behavior to Node while preserving generated file content, migration-safe copy behavior, package.json sync, and Quiver state metadata.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "node-init-docs-runtime",
+    "branch_name": "feature/QUIVER-02-node-init-docs-runtime"
+  },
+  "must": [
+    "Add a Node-native initialization module used by `create-quiver --name`",
+    "Copy templates and replace placeholders without invoking Bash, sed, cp, or chmod as required steps",
+    "Preserve existing files according to current init and migration behavior",
+    "Generate docs, specs, tools, package.json scripts, README, and `.quiver/state.json` with equivalent content",
+    "Keep `scripts/init-docs.sh` as a compatibility wrapper or legacy path where useful",
+    "Update package smoke so packaged installs initialize without Bash"
+  ],
+  "not_included": [
+    "Porting slice lifecycle scripts",
+    "Changing the spec/slice workflow semantics",
+    "Adding Windows CI matrix",
+    "Removing legacy shell scripts"
+  ],
+  "acceptance": [
+    "`node bin/create-quiver.js --name \"Smoke Project\" --dir <target>` initializes without spawning Bash",
+    "Generated project files match the current contract",
+    "Existing file preservation still works",
+    "Package smoke proves initialization from the tarball works through Node runtime",
+    "Unix `scripts/init-docs.sh` compatibility path still passes or clearly delegates to Node"
+  ],
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/init-docs.js",
+    "src/create-quiver/lib/templates.js",
+    "src/create-quiver/lib/package-json.js",
+    "scripts/init-docs.sh",
+    "scripts/ci/smoke-init-docs.sh",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/package-quiver.sh",
+    "specs/quiver-v12-cross-platform-native-runtime/SPEC.md",
+    "specs/quiver-v12-cross-platform-native-runtime/STATUS.md",
+    "specs/quiver-v12-cross-platform-native-runtime/EVIDENCE_REPORT.md",
+    "specs/quiver-v12-cross-platform-native-runtime/slices/slice-02-node-init-docs-runtime/slice.json"
+  ],
+  "tests": [
+    "node -c src/create-quiver/index.js",
+    "node -c src/create-quiver/lib/init-docs.js",
+    "bash scripts/ci/smoke-init-docs.sh",
+    "bash scripts/ci/smoke-create-quiver.sh",
+    "bash scripts/package-quiver.sh",
+    "git diff --check"
+  ],
+  "documentation": [
+    "specs/quiver-v12-cross-platform-native-runtime/SPEC.md",
+    "specs/quiver-v12-cross-platform-native-runtime/STATUS.md",
+    "specs/quiver-v12-cross-platform-native-runtime/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "slice-01-cross-platform-support-contract"
+  ],
+  "assumptions": [
+    "Node.js is the shared runtime across all supported systems",
+    "Current generated content should remain stable unless cross-platform support requires a wording change"
+  ],
+  "estimated_hours": 8,
+  "actual_hours": null,
+  "status": "draft",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": null
+}

package/specs/quiver-v12-cross-platform-native-runtime/slices/slice-03-node-migrate-analyze-doctor-flow/slice.json

@@ -0,0 +1,74 @@
+{
+  "slice_id": "slice-03-node-migrate-analyze-doctor-flow",
+  "ticket": "QUIVER-03",
+  "type": "feature",
+  "title": "Node Migrate, Analyze, and Doctor Flow",
+  "objective": "Make `migrate`, `analyze`, and `doctor` fully Node-native and Windows-safe.",
+  "description": "After initialization no longer requires Bash, the core maintenance loop must also avoid shell assumptions. This slice hardens path handling, metadata updates, and diagnostics for macOS, Linux, PowerShell, and CMD.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "node-core-flow",
+    "branch_name": "feature/QUIVER-03-node-core-flow"
+  },
+  "must": [
+    "Ensure `create-quiver migrate` uses the Node initialization runtime instead of Bash",
+    "Normalize paths with Node APIs and avoid POSIX-only separators in logic",
+    "Keep `analyze` and `doctor` usable from the project root without Bash",
+    "Update doctor diagnostics so Windows users see PowerShell/CMD-safe commands",
+    "Add focused tests or smoke fixtures for Windows-style paths and paths with spaces",
+    "Preserve existing metadata fields in `.quiver/state.json`"
+  ],
+  "not_included": [
+    "Porting `start-slice` or readiness gates",
+    "Adding GitHub Actions Windows matrix",
+    "Removing shell wrappers",
+    "Publishing a release"
+  ],
+  "acceptance": [
+    "`create-quiver migrate`, `analyze`, and `doctor` do not invoke Bash",
+    "Commands work when the project path contains spaces",
+    "Doctor output uses commands valid in PowerShell, CMD, macOS, and Linux",
+    "State metadata remains valid after migration and analysis",
+    "Existing smoke coverage still passes"
+  ],
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/paths.js",
+    "src/create-quiver/lib/state.js",
+    "src/create-quiver/lib/analyze.js",
+    "src/create-quiver/lib/doctor.js",
+    "scripts/ci/smoke-create-quiver.sh",
+    "specs/quiver-v12-cross-platform-native-runtime/SPEC.md",
+    "specs/quiver-v12-cross-platform-native-runtime/STATUS.md",
+    "specs/quiver-v12-cross-platform-native-runtime/EVIDENCE_REPORT.md",
+    "specs/quiver-v12-cross-platform-native-runtime/slices/slice-03-node-migrate-analyze-doctor-flow/slice.json"
+  ],
+  "tests": [
+    "node -c src/create-quiver/index.js",
+    "node bin/create-quiver.js migrate",
+    "node bin/create-quiver.js analyze",
+    "node bin/create-quiver.js doctor",
+    "bash scripts/ci/smoke-create-quiver.sh",
+    "git diff --check"
+  ],
+  "documentation": [
+    "specs/quiver-v12-cross-platform-native-runtime/SPEC.md",
+    "specs/quiver-v12-cross-platform-native-runtime/STATUS.md",
+    "specs/quiver-v12-cross-platform-native-runtime/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "slice-02-node-init-docs-runtime"
+  ],
+  "assumptions": [
+    "Analyze and doctor should remain read-mostly except for analysis metadata updates",
+    "`--dir` remains supported for explicit out-of-project targeting"
+  ],
+  "estimated_hours": 5,
+  "actual_hours": null,
+  "status": "draft",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": null
+}

package/specs/quiver-v12-cross-platform-native-runtime/slices/slice-04-node-slice-lifecycle-commands/slice.json

@@ -0,0 +1,81 @@
+{
+  "slice_id": "slice-04-node-slice-lifecycle-commands",
+  "ticket": "QUIVER-04",
+  "type": "feature",
+  "title": "Node Slice Lifecycle Commands",
+  "objective": "Port slice lifecycle and readiness gates from Bash scripts to Node CLI commands.",
+  "description": "The primary developer workflow still depends on Bash for `start-slice`, readiness checks, PR checks, cleanup, and scope checks. This slice introduces Node-native commands that preserve current behavior while working from PowerShell and CMD.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "node-slice-lifecycle",
+    "branch_name": "feature/QUIVER-04-node-slice-lifecycle"
+  },
+  "must": [
+    "Add CLI commands for `start-slice`, `check-slice`, `check-pr`, `cleanup-slice`, `check-scope`, and `refresh-active-slices`",
+    "Port slice JSON parsing and validation to Node",
+    "Port Git worktree creation, lookup, cleanup, and status checks to Node",
+    "Handle paths with spaces and Windows drive letters safely",
+    "Handle Windows executable-bit differences without false failures",
+    "Keep legacy `.sh` wrappers usable on Unix by delegating to the new CLI commands where practical"
+  ],
+  "not_included": [
+    "Changing the slice JSON schema unless required for compatibility",
+    "Changing branch naming rules",
+    "Changing one slice = one commit validation",
+    "Adding release publishing"
+  ],
+  "acceptance": [
+    "`npx create-quiver start-slice <slice.json>` creates or reuses the expected worktree",
+    "`npx create-quiver check-slice <slice.json>` validates the same contract as the current shell gate",
+    "`npx create-quiver check-pr <slice.json>` validates PR readiness without Bash",
+    "`npx create-quiver cleanup-slice <slice.json>` removes worktree and branch according to existing flags",
+    "Unix shell wrappers still pass existing smokes",
+    "Cross-platform path tests cover spaces and Windows-style path strings"
+  ],
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/git.js",
+    "src/create-quiver/lib/slice.js",
+    "src/create-quiver/lib/lifecycle.js",
+    "src/create-quiver/lib/readiness.js",
+    "src/create-quiver/lib/scope.js",
+    "scripts/start-slice.sh",
+    "scripts/check-slice-readiness.sh",
+    "scripts/check-pr-readiness.sh",
+    "scripts/cleanup-slice.sh",
+    "scripts/check-scope.sh",
+    "scripts/refresh-active-slices.sh",
+    "scripts/ci/smoke-workflow-gates.sh",
+    "scripts/ci/smoke-create-quiver.sh",
+    "specs/quiver-v12-cross-platform-native-runtime/SPEC.md",
+    "specs/quiver-v12-cross-platform-native-runtime/STATUS.md",
+    "specs/quiver-v12-cross-platform-native-runtime/EVIDENCE_REPORT.md",
+    "specs/quiver-v12-cross-platform-native-runtime/slices/slice-04-node-slice-lifecycle-commands/slice.json"
+  ],
+  "tests": [
+    "node -c src/create-quiver/index.js",
+    "bash scripts/ci/smoke-workflow-gates.sh",
+    "bash scripts/ci/smoke-create-quiver.sh",
+    "git diff --check"
+  ],
+  "documentation": [
+    "specs/quiver-v12-cross-platform-native-runtime/SPEC.md",
+    "specs/quiver-v12-cross-platform-native-runtime/STATUS.md",
+    "specs/quiver-v12-cross-platform-native-runtime/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "slice-03-node-migrate-analyze-doctor-flow"
+  ],
+  "assumptions": [
+    "Git remains an external dependency and is not bundled",
+    "The Node implementation should preserve current shell behavior before improving ergonomics"
+  ],
+  "estimated_hours": 10,
+  "actual_hours": null,
+  "status": "draft",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": null
+}

package/specs/quiver-v12-cross-platform-native-runtime/slices/slice-05-generated-project-scripts-and-migration/slice.json

@@ -0,0 +1,78 @@
+{
+  "slice_id": "slice-05-generated-project-scripts-and-migration",
+  "ticket": "QUIVER-05",
+  "type": "feature",
+  "title": "Generated Project Scripts and Migration",
+  "objective": "Update generated and migrated projects to use Node-native Quiver commands as the primary npm scripts.",
+  "description": "After Node-native lifecycle commands exist, generated projects should stop advertising Bash scripts as the primary workflow. This slice updates package templates, generated README content, migration behavior, and docs while preserving legacy script compatibility where useful.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "generated-scripts-migration",
+    "branch_name": "feature/QUIVER-05-generated-scripts-migration"
+  },
+  "must": [
+    "Update `package.template.json` scripts to call `create-quiver` commands",
+    "Update generated README and AI context commands to use Node-native commands",
+    "Teach `migrate` to add new npm scripts without deleting user scripts",
+    "Preserve legacy Bash script entries where needed with clear naming or documentation",
+    "Update doctor to recommend migration when generated scripts still only point to Bash",
+    "Add smokes for old projects migrated to Node-native npm scripts"
+  ],
+  "not_included": [
+    "Deleting legacy Bash scripts",
+    "Adding Windows CI matrix",
+    "Changing slice JSON schema",
+    "Publishing a release"
+  ],
+  "acceptance": [
+    "New projects include npm scripts that work without Bash",
+    "Existing projects gain Node-native scripts after `create-quiver migrate`",
+    "User-defined package scripts are preserved",
+    "Generated docs show `npx create-quiver start-slice`, `check-slice`, and `check-pr`",
+    "Doctor identifies projects that need script migration"
+  ],
+  "files": [
+    "package.template.json",
+    "package.json",
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/AI_CONTEXT.md.template",
+    "docs/WORKFLOW.md.template",
+    "scripts/init-docs.sh",
+    "src/create-quiver/index.js",
+    "scripts/ci/smoke-init-docs.sh",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/package-quiver.sh",
+    "specs/quiver-v12-cross-platform-native-runtime/SPEC.md",
+    "specs/quiver-v12-cross-platform-native-runtime/STATUS.md",
+    "specs/quiver-v12-cross-platform-native-runtime/EVIDENCE_REPORT.md",
+    "specs/quiver-v12-cross-platform-native-runtime/slices/slice-05-generated-project-scripts-and-migration/slice.json"
+  ],
+  "tests": [
+    "node -c src/create-quiver/index.js",
+    "bash scripts/ci/smoke-init-docs.sh",
+    "bash scripts/ci/smoke-create-quiver.sh",
+    "bash scripts/package-quiver.sh",
+    "git diff --check"
+  ],
+  "documentation": [
+    "specs/quiver-v12-cross-platform-native-runtime/SPEC.md",
+    "specs/quiver-v12-cross-platform-native-runtime/STATUS.md",
+    "specs/quiver-v12-cross-platform-native-runtime/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "slice-04-node-slice-lifecycle-commands"
+  ],
+  "assumptions": [
+    "Project-local devDependency usage should remain supported",
+    "npx usage should remain the recommended first path"
+  ],
+  "estimated_hours": 5,
+  "actual_hours": null,
+  "status": "draft",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": null
+}

package/specs/quiver-v12-cross-platform-native-runtime/slices/slice-06-cross-platform-ci-release-readiness/slice.json

@@ -0,0 +1,74 @@
+{
+  "slice_id": "slice-06-cross-platform-ci-release-readiness",
+  "ticket": "QUIVER-06",
+  "type": "ci",
+  "title": "Cross-Platform CI and Release Readiness",
+  "objective": "Prove native behavior on Linux, macOS, and Windows before declaring Windows support complete.",
+  "description": "The runtime port should only be considered complete when CI exercises the generated project lifecycle on all supported operating systems. This slice adds cross-platform GitHub Actions coverage, final documentation updates, and release readiness evidence.",
+  "git": {
+    "branch_type": "ci",
+    "base_branch": "main",
+    "branch_slug": "cross-platform-ci-release-readiness",
+    "branch_name": "ci/QUIVER-06-cross-platform-ci-release-readiness"
+  },
+  "must": [
+    "Add or update GitHub Actions matrix for `ubuntu-latest`, `macos-latest`, and `windows-latest`",
+    "Run core Quiver smokes on each OS without Bash as the required path",
+    "Package and install the tarball in CI on each OS",
+    "Validate initialization, migration, analysis, doctor, and slice lifecycle commands",
+    "Update support matrix from target support to verified support when CI passes",
+    "Prepare release notes and evidence for the next package release"
+  ],
+  "not_included": [
+    "Publishing the npm package",
+    "Removing legacy Bash wrappers",
+    "Adding non-Git version control support"
+  ],
+  "acceptance": [
+    "CI passes on Linux, macOS, and Windows",
+    "Windows CI runs PowerShell or CMD commands without Bash",
+    "Packaged CLI works on all matrix OSes",
+    "Docs state Windows native support only after the matrix is green",
+    "Evidence report links or records all relevant CI validations"
+  ],
+  "files": [
+    ".github/workflows/ci.yml",
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/SUPPORT_MATRIX.md.template",
+    "docs/TROUBLESHOOTING.md.template",
+    "CHANGELOG.md",
+    "scripts/ci/smoke-cross-platform.js",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/ci/smoke-workflow-gates.sh",
+    "specs/quiver-v12-cross-platform-native-runtime/SPEC.md",
+    "specs/quiver-v12-cross-platform-native-runtime/STATUS.md",
+    "specs/quiver-v12-cross-platform-native-runtime/EVIDENCE_REPORT.md",
+    "specs/quiver-v12-cross-platform-native-runtime/slices/slice-06-cross-platform-ci-release-readiness/slice.json"
+  ],
+  "tests": [
+    "GitHub Actions matrix on ubuntu-latest, macos-latest, and windows-latest",
+    "Node portable cross-platform smoke",
+    "bash scripts/package-quiver.sh",
+    "git diff --check"
+  ],
+  "documentation": [
+    "specs/quiver-v12-cross-platform-native-runtime/SPEC.md",
+    "specs/quiver-v12-cross-platform-native-runtime/STATUS.md",
+    "specs/quiver-v12-cross-platform-native-runtime/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "slice-05-generated-project-scripts-and-migration"
+  ],
+  "assumptions": [
+    "Windows support should not be declared final until CI proves the package path",
+    "Release publishing happens after this spec completes"
+  ],
+  "estimated_hours": 5,
+  "actual_hours": 5,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": "2026-04-22T00:00:00Z",
+  "started_at": "2026-04-22T00:00:00Z",
+  "completed_at": "2026-04-22T00:00:00Z"
+}

package/specs/quiver-v13-token-efficient-ai-context/EVIDENCE_REPORT.md

@@ -0,0 +1,28 @@
+# Quiver v0.13 Evidence Report
+
+**Spec:** quiver-v13-token-efficient-ai-context
+**Date:** 2026-04-23
+**Status:** Draft
+
+## Summary
+
+This spec will reduce AI token usage by improving Quiver's context contracts, generated prompts, analyzer map, and minimal doctor guidance without adding heavy retrieval infrastructure.
+
+## Slice Evidence
+
+| Slice | Status | Evidence |
+|-------|--------|----------|
+| slice-01 | Completed | README_FOR_AI.md, AI_ONBOARDING_PROMPT.md.template, WORKFLOW.md.template, and GITFLOW_PR_GUIDE.md.template now name onboarding, implementation, review, and debugging modes explicitly |
+| slice-02 | Completed | docs/DECISIONS.md.template added; docs/INDEX.md.template, README guidance, AI context, workflow, and PR guide now link or route to the decision log |
+| slice-03 | Completed | create-quiver analyze now writes Suggested Reading Order, Entry Points, Primary Config Files, Likely Test Commands, High-Signal Files, and Do Not Read First sections into PROJECT_MAP.md |
+
+## Required Final Evidence
+
+- Generated docs include the four token-efficient modes
+- Generated `docs/DECISIONS.md` exists and is linked from the docs index
+- Generated `docs/PROJECT_MAP.md` includes suggested reading order and high-signal files
+- Review guidance instructs agents to inspect `git diff` before opening full files
+- Implementation guidance instructs agents to start from `slice.json` and declared files
+- Debug guidance preserves command, exit code, first relevant error, stacktrace, and log path when available
+- `doctor` prints a concise token-efficient next step after analysis succeeds
+- Smokes validate the new generated artifacts and key sections

package/specs/quiver-v13-token-efficient-ai-context/SPEC.md

@@ -0,0 +1,68 @@
+# Quiver v0.13 - Token-Efficient AI Context
+
+**Date:** 2026-04-23
+**Status:** Draft
+
+Slice numbering resets here: this spec starts at `slice-01` and does not continue any previous spec's numbering.
+
+## Objective
+
+Reduce AI token usage in Quiver workflows by making the generated context, prompts, analyzer output, and doctor guidance more selective, structured, and mode-aware without adding heavyweight retrieval infrastructure.
+
+## Scope
+
+### Included
+
+- Define token-efficient AI work modes for onboarding, implementation, review, and debugging
+- Teach generated prompts to prefer maps, metadata, diffs, and scoped files before full source reads
+- Add a lightweight decision log contract
+- Improve `PROJECT_MAP.md` so it becomes the first useful reading index for AI agents
+- Preserve the existing spec/slice workflow and one commit per slice discipline
+- Add smoke coverage for the generated token-efficiency artifacts and guidance
+
+### Excluded
+
+- Embeddings, vector databases, or mandatory semantic indexes
+- Automatic multi-language call graph generation
+- Automatic memory pruning without human review
+- Exact token counting or provider-specific billing integrations
+- A new orchestration command such as `create-quiver context`
+
+## Token-Efficient Modes
+
+Quiver should guide AI agents differently depending on the task:
+
+- **Onboarding:** read `docs/PROJECT_MAP.md`, `docs/AI_CONTEXT.md`, and `docs/AI_ONBOARDING_PROMPT.md` before source files
+- **Implementation:** read `slice.json`, declared files, nearby tests, and only then adjacent source
+- **Review:** inspect `git diff` and declared slice scope before full files
+- **Debug:** inspect the command, exit code, first relevant error, stacktrace, and nearest changed code before long logs
+
+## Principles
+
+- Prefer durable project context over repeated chat history
+- Prefer deltas over full files when reviewing or iterating
+- Prefer summaries with evidence over pasted logs
+- Keep new artifacts few, useful, and easy to maintain
+- Make analyzer output more valuable before adding infrastructure
+
+## Slices
+
+| Slice | Title | Status | Spec |
+|-------|-------|--------|------|
+| 01 | Token-Efficient AI Modes Guidance | Completed | [slice-01](./slices/slice-01-token-efficient-ai-modes-guidance/slice.json) |
+| 02 | Decision Log | Completed | [slice-02](./slices/slice-02-decision-log-context-checkpoint/slice.json) |
+| 03 | Project Map Reading Order | Completed | [slice-03](./slices/slice-03-project-map-reading-order/slice.json) |
+
+## Definition of Done
+
+- Generated projects document mode-aware AI reading rules
+- Generated projects include `docs/DECISIONS.md`
+- `create-quiver analyze` writes a `PROJECT_MAP.md` with suggested reading order and high-signal files
+- `doctor` gives a minimal token-efficient next step without becoming noisy
+- Smokes verify the generated artifacts and key sections
+
+## Relationship to v14
+
+- v13 slice-02 is narrowed to `DECISIONS.md` only; assumptions and context-efficiency content are produced by v14 slice-01 in `docs/ai/DEEP.md`
+- v13 slice-04 was absorbed into v14 slice-05; doctor warnings and smoke assertions for token-efficiency artifacts live there now
+- Recommended execution order: v13 slice-01 -> v13 slice-02 (narrowed) -> v13 slice-03 -> v14 slice-01 -> v14 slice-02 -> v14 slice-03 -> v14 slice-04 -> v14 slice-05

package/specs/quiver-v13-token-efficient-ai-context/STATUS.md

@@ -0,0 +1,26 @@
+# Quiver v0.13 Spec Status
+
+**Spec:** quiver-v13-token-efficient-ai-context
+**Last updated:** 2026-04-23
+
+Slice numbering is local to this spec. The first slice is `slice-01`.
+
+## Status
+
+| Slice | Title | Status | PR | Estimated hours | Actual hours |
+|-------|-------|--------|----|-----------------|--------------|
+| slice-01 | Token-Efficient AI Modes Guidance | Completed | - | 3 | 3 |
+| slice-02 | Decision Log | Completed | - | 2 | 2 |
+| slice-03 | Project Map Reading Order | Completed | - | 5 | 5 |
+
+## Progress
+
+- Completed slices: 3 / 3
+- Estimated hours: 10
+- Actual hours: 10
+
+## Blockers
+
+| Slice | Blocker | Since | Action needed |
+|-------|---------|-------|---------------|
+| - | - | - | - |

package/specs/quiver-v13-token-efficient-ai-context/slices/slice-01-token-efficient-ai-modes-guidance/slice.json

@@ -0,0 +1,65 @@
+{
+  "slice_id": "slice-01-token-efficient-ai-modes-guidance",
+  "ticket": "QUIVER-01",
+  "type": "docs",
+  "title": "Token-Efficient AI Modes Guidance",
+  "objective": "Define mode-aware AI reading rules so agents spend tokens on the right artifacts for onboarding, implementation, review, and debugging.",
+  "description": "The current AI guidance encourages structured onboarding, but it does not clearly separate when to use map-first, slice-scope-first, diff-first, or error-first workflows. This slice makes those modes explicit in the generated guidance without introducing new runtime behavior.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "token-efficient-ai-modes-guidance",
+    "branch_name": "docs/QUIVER-01-token-efficient-ai-modes-guidance"
+  },
+  "must": [
+    "Document the four AI work modes: onboarding, implementation, review, and debugging",
+    "Update `README_FOR_AI.md` with token-efficient reading rules",
+    "Update `docs/AI_ONBOARDING_PROMPT.md.template` to start from maps and metadata before source files",
+    "Update `docs/WORKFLOW.md.template` with mode-aware context selection",
+    "Update `docs/GITFLOW_PR_GUIDE.md.template` with diff-first review guidance"
+  ],
+  "not_included": [
+    "Adding new generated files",
+    "Changing analyzer output",
+    "Changing doctor output",
+    "Adding semantic search or embeddings"
+  ],
+  "acceptance": [
+    "AI guidance names all four modes explicitly",
+    "Review guidance instructs agents to inspect `git diff` before opening full files",
+    "Implementation guidance instructs agents to start from `slice.json` and declared files",
+    "Debug guidance preserves command, exit code, first relevant error, stacktrace, and log path when available"
+  ],
+  "files": [
+    "README_FOR_AI.md",
+    "docs/AI_ONBOARDING_PROMPT.md.template",
+    "docs/WORKFLOW.md.template",
+    "docs/GITFLOW_PR_GUIDE.md.template",
+    "specs/quiver-v13-token-efficient-ai-context/SPEC.md",
+    "specs/quiver-v13-token-efficient-ai-context/STATUS.md",
+    "specs/quiver-v13-token-efficient-ai-context/EVIDENCE_REPORT.md",
+    "specs/quiver-v13-token-efficient-ai-context/slices/slice-01-token-efficient-ai-modes-guidance/slice.json"
+  ],
+  "tests": [
+    "rg check for onboarding, implementation, review, and debugging modes",
+    "git diff --check"
+  ],
+  "documentation": [
+    "README_FOR_AI.md",
+    "docs/AI_ONBOARDING_PROMPT.md.template",
+    "docs/WORKFLOW.md.template",
+    "docs/GITFLOW_PR_GUIDE.md.template"
+  ],
+  "dependencies": [],
+  "assumptions": [
+    "Mode-aware guidance is more useful than one generic token-efficiency checklist",
+    "Detailed enforcement can wait until the generated artifacts exist"
+  ],
+  "estimated_hours": 3,
+  "actual_hours": 3,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": "2026-04-23"
+}

package/specs/quiver-v13-token-efficient-ai-context/slices/slice-02-decision-log-context-checkpoint/slice.json

@@ -0,0 +1,64 @@
+{
+  "slice_id": "slice-02-decision-log-context-checkpoint",
+  "ticket": "QUIVER-02",
+  "type": "docs",
+  "title": "Decision Log",
+  "objective": "Add a durable decision log so AI agents do not re-litigate past decisions.",
+  "description": "Quiver already externalizes project context, but it lacks a dedicated decision log. This slice adds that one durable artifact; assumptions and context-efficiency notes are handled by the tiered context pack in v14 instead.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "decision-log-context-checkpoint",
+    "branch_name": "docs/QUIVER-02-decision-log-context-checkpoint"
+  },
+  "must": [
+    "Add `docs/DECISIONS.md.template` with a compact decision log table",
+    "Generate `docs/DECISIONS.md` during init and migration",
+    "Link `docs/DECISIONS.md` from `docs/INDEX.md.template` and generated README guidance where appropriate"
+  ],
+  "not_included": [
+    "Creating a separate assumptions file",
+    "Automatic decision extraction",
+    "Token counting",
+    "Deleting existing context sections"
+  ],
+  "acceptance": [
+    "New projects contain `docs/DECISIONS.md`",
+    "Migration adds `docs/DECISIONS.md` without overwriting existing docs",
+    "Existing user package scripts and docs are preserved during migration"
+  ],
+  "files": [
+    "docs/DECISIONS.md.template",
+    "docs/INDEX.md.template",
+    "scripts/init-docs.sh",
+    "src/create-quiver/lib/init-docs.js",
+    "scripts/ci/smoke-init-docs.sh",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/package-quiver.sh",
+    "specs/quiver-v13-token-efficient-ai-context/SPEC.md",
+    "specs/quiver-v13-token-efficient-ai-context/EVIDENCE_REPORT.md",
+    "specs/quiver-v13-token-efficient-ai-context/slices/slice-02-decision-log-context-checkpoint/slice.json"
+  ],
+  "tests": [
+    "bash scripts/ci/smoke-init-docs.sh",
+    "bash scripts/ci/smoke-create-quiver.sh",
+    "bash scripts/package-quiver.sh",
+    "git diff --check"
+  ],
+  "documentation": [
+    "docs/DECISIONS.md.template"
+  ],
+  "dependencies": [
+    "slice-01-token-efficient-ai-modes-guidance"
+  ],
+  "assumptions": [
+    "A single decision log is enough for now"
+  ],
+  "estimated_hours": 2,
+  "actual_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": "2026-04-23"
+}