create-quiver 0.6.0 → 0.8.0

package/.claude/settings.local.json

@@ -0,0 +1,45 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git fetch *)",
+      "Bash(git checkout *)",
+      "Bash(git add *)",
+      "Bash(git commit -m ' *)",
+      "Bash(git cherry-pick *)",
+      "Bash(git reset *)",
+      "Bash(gh pr create --title 'docs: register v17-v22 orchestration plan and park web console idea' --base main --head docs/register-orchestration-plan-park-web-console --body ' *)",
+      "Bash(gh auth *)",
+      "Bash(gh pr *)",
+      "Bash(node -e \"const g=require\\('./src/create-quiver/lib/slice-graph'\\); const slices=g.readAllSlices\\('.'\\); console.log\\('Total slices:', slices.length\\); const graph=g.buildGraph\\(slices\\); const levels=g.computeLevels\\(graph\\); console.log\\('Levels:', levels.length\\);\")",
+      "Bash(npx . plan)",
+      "Bash(git pull *)",
+      "Read(//Users/fabrijk/Documents/Work/Proyectos Personales/nika/frameworks/.worktrees/quiver/bugfix-QUIVER-01-fix-legacy-dependency-resolution/**)",
+      "Bash(node --test tests/)",
+      "Bash(node --test tests/**/*.test.js)",
+      "Bash(node bin/create-quiver.js plan)",
+      "Bash(echo \"EXIT_$?\")",
+      "Bash(node bin/create-quiver.js plan --json)",
+      "Bash(node -e \"const d=JSON.parse\\(require\\('fs'\\).readFileSync\\('/dev/stdin','utf8'\\)\\); console.log\\('plan items:', Array.isArray\\(d.plan\\) ? d.plan.length : 'NOT ARRAY'\\); console.log\\('critical_path:', Array.isArray\\(d.critical_path\\)\\); console.log\\('total_hours:', typeof d.total_hours\\); process.exit\\(Array.isArray\\(d.plan\\) && Array.isArray\\(d.critical_path\\) && typeof d.total_hours === 'number' ? 0 : 1\\)\")",
+      "Bash(grep -v \"^\\\\-\\\\-$\")",
+      "Bash(echo \"EXIT:$?\")",
+      "Bash(node -e \"const d=JSON.parse\\(require\\('fs'\\).readFileSync\\('/tmp/plan_json.txt','utf8'\\)\\); console.log\\('plan:', Array.isArray\\(d.plan\\) ? d.plan.length + ' items' : 'INVALID'\\); console.log\\('critical_path:', Array.isArray\\(d.critical_path\\)\\); console.log\\('total_hours:', typeof d.total_hours\\)\")",
+      "Bash(xargs git branch -d)",
+      "Bash(git branch *)",
+      "Read(//private/tmp/**)",
+      "Read(//Users/fabrijk/Documents/Work/Proyectos Personales/nika/frameworks/quiver-v18-slice02/**)",
+      "Bash(git worktree *)",
+      "Bash(git ls-remote *)",
+      "Bash(node *)",
+      "Bash(npm view *)",
+      "Bash(bash scripts/release-quiver.sh)",
+      "Bash(git stash *)",
+      "Bash(npm whoami *)",
+      "Bash(bash scripts/release-quiver.sh --publish-current)",
+      "Bash(npm pkg *)",
+      "Bash(NPM_TOKEN=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 npm publish --access public)",
+      "Bash(NPM_TOKEN=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 npm publish --access public)",
+      "Bash(npm info *)",
+      "Bash(npm publish *)"
+    ]
+  }
+}

package/.github/workflows/ci.yml

@@ -22,16 +22,17 @@ jobs:
 
       - name: Validate slice templates
         run: |
-          node -e "JSON.parse(require('fs').readFileSync('specs/[project-name]/slices/slice-template/slice.json', 'utf8'))"
-          node -e "JSON.parse(require('fs').readFileSync('specs/quiver-v01/slices/slice-01-legal-integrity/slice.json', 'utf8'))"
+          node -e "const fs=require('fs'); const {parseJsonWithComments}=require('./src/create-quiver/lib/json'); parseJsonWithComments(fs.readFileSync('specs/[project-name]/slices/slice-template/slice.json', 'utf8'))"
+          node -e "const fs=require('fs'); const {parseJsonWithComments}=require('./src/create-quiver/lib/json'); parseJsonWithComments(fs.readFileSync('specs/quiver-v01/slices/slice-01-legal-integrity/slice.json', 'utf8'))"
 
-  smoke-init-docs:
+  cross-platform-smoke:
     strategy:
       fail-fast: false
       matrix:
         os:
           - ubuntu-latest
           - macos-latest
+          - windows-latest
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout
@@ -42,33 +43,9 @@ jobs:
         with:
           node-version: 22
 
-      - name: Run init-docs smoke
-        run: bash scripts/ci/smoke-init-docs.sh "Smoke Project"
+      - name: Run cross-platform smoke
+        run: node scripts/ci/smoke-cross-platform.js
 
-  smoke-workflow-gates:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-
-      - name: Run workflow gate smoke
-        run: bash scripts/ci/smoke-workflow-gates.sh
-
-  smoke-create-quiver:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-
-      - name: Run create-quiver smoke
-        run: bash scripts/ci/smoke-create-quiver.sh
+      - name: Run tiered pack smoke
+        shell: bash
+        run: bash scripts/ci/smoke-tiered-pack.sh

package/AGENTS.md.template

@@ -0,0 +1,41 @@
+# AGENTS Router
+
+Purpose
+
+This file is the universal router for AI agents in Quiver-generated projects. Read it before any other project context when you need to decide how deep to load.
+
+## Reading Budget
+
+- Planning: up to 10000 tokens
+- Execution: under 2000 tokens before the first action
+- Debug: under 1000 tokens before proposing a hypothesis
+
+## Reading Order
+
+1. QUICK
+2. STANDARD if QUICK is insufficient
+3. DEEP only when history or past decisions are requested
+
+## Output Policy
+
+- Do not restate the task before acting.
+- Do not summarize diffs after edits.
+- Keep confirmations to one sentence max.
+
+## Slice Execution Rules
+
+- If `docs/ai/ACTIVE_SLICE.md` exists, treat it as the source of truth.
+- Do not read `SPEC.md` unless `ACTIVE_SLICE.md` points to it.
+- Stay inside the slice `allowed_files` when an active slice is present.
+- Prefer the slice tests and checklist over general repo context.
+
+## Links
+
+- QUICK: `./docs/ai/QUICK.md`
+- STANDARD: `./docs/ai/STANDARD.md`
+- DEEP: `./docs/ai/DEEP.md`
+- Project Map: `./docs/PROJECT_MAP.md`
+- AI Context: `./docs/AI_CONTEXT.md`
+- Decision Log: `./docs/DECISIONS.md`
+- AI Onboarding Prompt: `./docs/AI_ONBOARDING_PROMPT.md`
+- Active Slice: `./docs/ai/ACTIVE_SLICE.md`

package/BACKLOG.md

@@ -0,0 +1,139 @@
+# Quiver Backlog
+
+> **Purpose:** Emerging patterns and ideas that are not yet scoped as specs.
+> Reviewed periodically to decide which ones graduate into a spec.
+>
+> **Audience:** The Quiver maintainer and any AI agent doing project onboarding.
+> **Not to be confused with:** `ROADMAP.md` (committed work with versions) or
+> active specs in `specs/quiver-vNN-*/` (in-progress or completed work).
+
+## How this file works
+
+- Each entry is an **idea, pattern, or methodology** observed in real use.
+- Entries stay here until one of three things happens:
+  1. Enough evidence accumulates to promote it to a spec (move to `ROADMAP.md`).
+  2. Evidence shows it is not worth formalizing (mark `parked` with reasoning).
+  3. It turns out to already exist elsewhere (mark `resolved` with the link).
+- **Do not delete parked entries.** The reasoning is valuable when the idea comes back.
+- **Do not auto-promote.** A pattern graduates to a spec only when the maintainer confirms it is time.
+
+## Entry template
+
+```
+### [Short name]
+
+- **Observed:** YYYY-MM-DD
+- **Status:** emerging | evaluating | promoted | parked | resolved
+- **Evidence so far:** <how often has this pattern appeared in real work>
+- **Problem it solves:** <one or two sentences>
+- **Proposed shape:** <what a formalization would look like>
+- **Cost to formalize:** <rough estimate in slices/hours>
+- **Reasons to wait:** <what would count as insufficient evidence>
+- **Trigger to promote:** <concrete threshold to move into ROADMAP.md>
+- **Related:** <links to specs, conversations, or handoffs>
+```
+
+---
+
+## Active Entries
+
+### Slice Orchestration and Tooling Commands
+
+- **Observed:** 2026-04-23
+- **Status:** planned
+- **Evidence so far:** 0 real cases. Drafted by the maintainer anticipating multi-model coordination (Opus/GPT-5.4 planning, Sonnet/GPT-5.4 Mini/Qwen Code execution) and visibility pain once specs accumulate.
+- **Problem it solves:** Today coordinating multiple agents across pending slices requires ad-hoc grep, ls, and git commands. There is no canonical way to ask "what runs next", "what can run in parallel", "what is this repo's state", or "how expensive is this slice to load".
+- **Proposed shape:**
+  - v17 Orchestration Foundation (CI matrix, `lib/slice-graph.js`, `depends_on` validation)
+  - v18 Slice Orchestration (`plan`, `graph`, `next`)
+  - v19 Project Visibility (`status`, `estimate`, `lint-spec`)
+  - v20 Context Diagnostics (`cost`, `diff-pack`, `replay`)
+  - v21 Slice Archaeology (`archive`, `blame-slice`)
+  - v22 Deferred Tooling (`fork-slice`, `squash-spec`, `share`, evidence-gated per slice)
+- **Cost to formalize:** ~55h across 15 slices in 4 specs (v19–v22). Spec/slice files drafted under `drafts/v19-v22-orchestration-followups`.
+- **Reasons to wait:** v17 and v18 shipped. v18 must pass its validation checkpoint (≥1 week real use) before v19 starts. Building orchestration before validating the existing commands risks reinforcing a design that does not earn its place.
+- **Trigger to promote (per spec):**
+  - v19: immediately after v18 checkpoint passes (≥1 week real use of `plan`, `graph`, `next`)
+  - v20–v21: previous spec validation checkpoint passed (≥1 week real use)
+  - v22 per slice: explicit occurrence recorded in this file for each of `fork-slice`, `squash-spec`, `share`
+- **Related:**
+  - `drafts/v19-v22-orchestration-followups` (parked spec drafts)
+  - `ROADMAP.md` Orchestration and Tooling section
+
+### Handoff Contract
+
+- **Observed:** 2026-04-23
+- **Status:** emerging
+- **Evidence so far:** 1 real case. `specs/quiver-v14-tiered-context-pack/HANDOFF.md`, written to reconcile v13 and v14 before either could execute. Used to delegate meta-work to a separate agent with self-contained context, explicit validation, and negative constraints.
+- **Problem it solves:** Today Quiver has no first-class vehicle for work that is neither a slice (product code) nor a spec (planning document). Examples: reconciling two in-flight specs, delegating a cleanup task to a different agent, transferring planning context from a planning-tier model (Opus, GPT-5.4) to an execution-tier model (Sonnet, GPT-5.4 Mini, Qwen Code). Without a vehicle, these tasks happen in ad-hoc chats or untracked commits and lose reproducibility.
+- **Proposed shape:**
+  - `HANDOFF.md.template` with canonical sections (Background, What you will change, Validation checklist, Out of scope, Expected deliverable, Constraints)
+  - Convention for location (for example `specs/<spec>/HANDOFF-<slug>.md` or `specs/handoffs/<date>-<slug>.md`)
+  - Convention for lifecycle (created when needed, deleted after validation passes)
+  - Optional `create-quiver new-handoff <slug>` command
+  - Optional `create-quiver check-handoff <path>` that validates canonical sections
+  - Optional smoke that confirms merged handoffs followed the contract
+  - **Explicitly not** a new `type` in `slice.json` — handoffs are orthogonal to slices, not a variant of them
+- **Cost to formalize:** ~2-3 slices, ~8-10 hours
+- **Reasons to wait:** A single occurrence is not enough evidence that this needs tooling. The ad-hoc `HANDOFF.md` already works. Formalizing now risks building infrastructure for a case that may not repeat often enough to justify the surface area.
+- **Trigger to promote:** 3 or more organic handoffs appear in real work over 2-3 months without this backlog entry being revisited. Or: one external user reports they wrote a handoff-like artifact for their own spec.
+- **Related:**
+  - `specs/quiver-v14-tiered-context-pack/HANDOFF.md` (the first real handoff)
+  - `specs/quiver-v16-handoff-contract/SPEC.md` (draft spec created, pending evidence and execution)
+  - `ROADMAP.md` "Post-Checkpoint Plan" section
+  - Multi-model setup context: planning models (Opus, GPT-5.4) to execution models (Sonnet, GPT-5.4 Mini, Qwen Code)
+
+---
+
+## Parked Entries
+
+### Local Web Console for Slice Visualization
+
+- **Observed:** 2026-05-12
+- **Status:** parked
+- **Evidence so far:** 0 real cases. Standalone prototype explored (`devflow-console`, Express + WebSocket + React, ~350 LoC, lives outside this repo at `/Users/fabrijk/Downloads/devflow-console`).
+- **Problem it would solve:** Visual graph of slices (parallel vs sequential, file-level conflicts), button-driven workflow, in-browser terminal, reusable prompts panel.
+- **Why parked:**
+  - Breaks Quiver's CLI-first identity; turns a scaffolder into a mini-IDE.
+  - ~80% of visible value duplicates planned CLI work in v19–v22 (`quiver:status`, `quiver:estimate`, etc.) and already-shipped v18 (`quiver:plan`, `quiver:graph`, `quiver:next`).
+  - Real security surface: arbitrary command execution via HTTP, DNS rebinding against localhost, open CORS, no auth, race conditions on shared filesystem state.
+  - Adds heavy maintenance cost (React + Vite + Express + ws) to a package distributed as a lightweight `npx create-quiver`.
+  - Multi-model agents (the actual audience for Quiver workflows) do not use UI.
+- **Cheaper alternatives identified first:**
+  - `quiver:graph --html` static export (no server, single self-contained file). Explore as subflag of v18 if Mermaid proves insufficient.
+  - Mermaid output shipped in v18 slice-03, renders natively in VSCode/IntelliJ.
+  - Optional VSCode extension as companion if UI is ever justified.
+- **Trigger to promote:**
+  1. v18 (`plan`, `graph`, `next`) is used in real work for ≥3 weeks after its checkpoint passes.
+  2. Mermaid/ASCII output of `quiver:graph` is documented as insufficient with concrete friction examples.
+  3. `quiver:graph --html` static export is built and also proves insufficient.
+  4. If ever implemented: must be a separate companion package (e.g. `@quiver/console`) or VSCode extension — never integrated into `create-quiver` core.
+- **Related:**
+  - Reference prototype: outside repo (not tracked)
+  - `specs/quiver-v18-slice-orchestration/` — CLI alternative already shipped
+
+## Resolved Entries
+
+_None yet._
+
+---
+
+## Review cadence
+
+Revisit this file:
+
+- After each spec reaches its validation checkpoint
+- Before writing a new spec (to confirm the work is not already an emerging backlog pattern)
+- When adding a new entry (check if it overlaps with an existing one)
+
+## Discovery hooks
+
+This file is referenced from:
+
+- `README.md` References section
+- `README_FOR_AI.md` onboarding guidance
+- `ROADMAP.md` Post-Checkpoint Plan
+
+If you are an AI agent doing onboarding, read this file after `ROADMAP.md` and
+before proposing any new spec. Ideas that look novel may already be tracked
+here with documented reasons not to formalize them yet.

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-05-13
+
+### Added
+
+- `quiver:plan` — lists all pending slices in dependency order with estimated hours, status, and critical path
+- `quiver:graph` — visualizes the slice dependency graph in ASCII tree, Mermaid, and DOT formats
+- `quiver:next` — suggests the next ready slice; supports `--all-ready`, `--json`, and `--auto-start`
+- Slice graph library — `readAllSlices`, `buildGraph`, `topoSort`, `computeLevels`, `detectFileConflicts` for programmatic graph access
+- `depends_on` and `parallel_safe` fields with validation in `check-slice`
+- JSON-with-comments support for slice templates
+- Cross-platform CI matrix covering macOS, Linux, and Windows for the Node-native runtime
+- Node-native generated project npm scripts and additive migration support for existing projects
+
+### Fixed
+
+- `quiver:plan` no longer crashes on repos with legacy bare spec names in the `dependencies` field (e.g. `"quiver-v01"`) — these are silently dropped instead of throwing `MISSING_DEPENDENCY`
+
 ## [0.4.0] - 2026-04-21
 
 ### Added

package/README.md

@@ -34,18 +34,49 @@ npx create-quiver --name "Project Name" --dir "/Users/me/My Project"
 
 ### 2. Analyze And Validate
 
-Run the local analyzer and then validate the generated contract:
+Run the local analyzer and then validate the generated contract from the project root:
 
 ```bash
-npx create-quiver analyze --dir ./target-repo
-npx create-quiver doctor --dir ./target-repo
+npx create-quiver analyze
+npx create-quiver graph
+npx create-quiver doctor
+npx create-quiver next
 ```
 
-If you are working in the current directory, use `--dir .`.
+Use `npx create-quiver graph --format mermaid` for PR-ready Markdown or `npx create-quiver graph --format dot` for Graphviz source.
+
+If you need to target another directory from outside the project, pass `--dir` explicitly. For the current project root, omit it.
 
 The analyzer creates `docs/PROJECT_SCAN.json` and `docs/PROJECT_MAP.md`. These files give the AI agent a deterministic project map before it edits context docs.
 
-The doctor checks the generated project contract and prints the next workflow steps. If the scan artifacts are missing, it recommends `npx create-quiver analyze --dir .` first.
+The doctor checks the generated project contract and prints the next workflow steps. If the scan artifacts are missing, it recommends `npx create-quiver analyze` first.
+`npx create-quiver next` prints the next ready slice and can auto-start it behind a confirmation prompt.
+
+### Project NPM Scripts
+
+Generated projects include `quiver:*` npm scripts that call the Node CLI and are the preferred repeatable workflow:
+
+```bash
+npm run quiver:analyze
+npm run quiver:plan
+npm run quiver:graph
+npm run quiver:next
+npm run quiver:doctor
+npm run quiver:migrate
+npm run quiver:start-slice -- specs/<project-slug>/slices/slice-01/slice.json
+npm run quiver:check-slice -- specs/<project-slug>/slices/slice-01/slice.json
+npm run quiver:check-pr -- specs/<project-slug>/slices/slice-01/slice.json
+npm run quiver:cleanup-slice -- specs/<project-slug>/slices/slice-01/slice.json
+npm run quiver:check-scope -- specs/<project-slug>/slices/slice-01/slice.json
+npm run quiver:refresh-active-slices
+```
+
+`npm run quiver:graph` prints the tree view by default. Pass `--format mermaid` or `--format dot` when you need an exportable graph artifact.
+`npm run quiver:next` points to the next ready slice and can auto-start it behind a confirmation prompt.
+`npx create-quiver next --all-ready` shows the full ready level when you want the whole queue instead of one slice.
+
+The legacy Bash wrappers remain in `tools/scripts/` for compatibility, but new project-level automation should prefer the `quiver:*` scripts and the direct `npx create-quiver ...` commands.
+`npm run quiver:migrate` is only for projects that were already initialized by Quiver.
 
 ### 3. Upgrade Existing Projects
 
@@ -53,20 +84,33 @@ If the project already had Quiver from an older version, upgrade it from the pro
 
 ```bash
 cd /path/to/your-project
-npx create-quiver migrate --dir .
-npx create-quiver analyze --dir .
-npx create-quiver doctor --dir .
+npx create-quiver migrate
+npx create-quiver analyze
+npx create-quiver graph
+npx create-quiver doctor
+npx create-quiver next
+```
+
+Use `npx create-quiver graph --format mermaid` for GitHub-friendly graph embeds or `npx create-quiver graph --format dot` for Graphviz pipelines.
+
+If the project never ran Quiver initialization before, do not use `migrate` as bootstrap. Run:
+
+```bash
+npx create-quiver --name "Project Name"
 ```
 
 If your team prefers a pinned local dependency, update the package first and then run the same flow:
 
 ```bash
 npm install --save-dev create-quiver@latest
-npx create-quiver migrate --dir .
-npx create-quiver analyze --dir .
-npx create-quiver doctor --dir .
+npx create-quiver migrate
+npx create-quiver analyze
+npx create-quiver graph
+npx create-quiver doctor
 ```
 
+The tree output remains the default, but Mermaid and DOT are available on demand for exported docs and slide decks.
+
 ### 4. Ask The AI To Prepare Context
 
 Open your AI agent in the target project and run this short handoff:
@@ -85,7 +129,7 @@ After the context docs are reviewed:
 
 1. Define or refine `specs/<project-slug>/SPEC.md`.
 2. Create the first slice from `specs/<project-slug>/slices/slice-template/slice.json`.
-3. Start work with `tools/scripts/start-slice.sh <slice.json>`.
+3. Start work with `npx create-quiver start-slice <slice.json>` or `npm run quiver:start-slice -- <slice.json>`.
 4. Make one commit per slice.
 5. Open one PR per spec.
 
@@ -95,10 +139,16 @@ Slice numbering is local to each spec: every new spec starts at `slice-01`.
 
 - Node.js and npm for the installer
 - Git for slice branches, worktrees, and PR workflow checks
-- macOS or Linux as the primary supported shell environment
+- macOS, Linux, and Windows PowerShell/CMD are the target developer environments for the cross-platform runtime work
+
+Windows native support is verified only when the cross-platform CI matrix is green. Bash remains a legacy compatibility path until the runtime slices land.
 
 See the generated `docs/SUPPORT_MATRIX.md` for the detailed support contract.
 
+## Cross-Platform Support
+
+Quiver is targeting native support on macOS, Linux, and Windows PowerShell/CMD. Bash is a legacy compatibility path until the runtime slices land, so the long-term contract is a Node-first workflow rather than a Bash-first one. The CI matrix must be green before Windows is considered fully verified.
+
 ## What Gets Generated
 
 Quiver generates a project-local workflow under:
@@ -106,6 +156,10 @@ Quiver generates a project-local workflow under:
 - `docs/` for project context, workflow, support, troubleshooting, and AI guidance
 - `docs/PROJECT_SCAN.json` and `docs/PROJECT_MAP.md` after `create-quiver analyze`
 - `docs/AI_ONBOARDING_PROMPT.md` as the generated handoff prompt for the AI agent
+- `specs/<project-slug>/HANDOFF.md` as the exceptional transfer artifact between agents or phases
+- `npx create-quiver new-handoff <spec-slug>` to scaffold an optional handoff artifact when work needs to move between agents or phases
+- `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md` to validate a transferred handoff before execution
+- `docs/COMMANDS.md` as the canonical command reference table for orchestration
 - `specs/<project-slug>/` for the project spec, status, evidence, and slice contracts
 - `tools/scripts/` for slice lifecycle and readiness gates
 - `.github/` for default PR, issue, and CI templates
@@ -122,7 +176,7 @@ Use the manual flow only when developing Quiver locally or testing a template ch
 ```
 
 The CLI path is the supported adoption path for users.
-For analyzed projects, the agent handoff prompt lives at `docs/AI_ONBOARDING_PROMPT.md` in the generated project.
+For analyzed projects, the agent handoff prompt lives at `docs/AI_ONBOARDING_PROMPT.md` in the generated project. If a bounded transfer between agents or phases is needed, scaffold `specs/<project-slug>/HANDOFF.md` with `npx create-quiver new-handoff <spec-slug>` and validate it with `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md`.
 
 ## For AI Agents
 

package/README_FOR_AI.md

@@ -7,11 +7,33 @@ The first AI job in a generated project is context preparation, not product impl
 Important: slice numbering resets inside each spec. `slice-01` is the first slice of that spec, not a global repo counter.
 The canonical installer entrypoint is `npx create-quiver` run from the target project root.
 Do not recommend global installation; use `npx` or a project-local devDependency when the team needs a pinned version.
-The post-init contract is validated with `npx create-quiver doctor --dir <project>`.
-If the project already exists from an older Quiver version, run `npx create-quiver migrate --dir <project>` before `analyze`.
+The post-init contract is validated with `npx create-quiver doctor` from the project root.
+If the project already exists from an older Quiver version and was previously initialized by Quiver, run `npx create-quiver migrate` before `analyze` from the project root.
+If the project was never initialized by Quiver, do not use `migrate` as bootstrap; run `npx create-quiver --name "Project Name"` first.
+Generated projects also get `quiver:*` npm scripts that call the Node CLI directly; prefer those for repeatable project workflows, including `quiver:plan` for sequential planning, `quiver:graph` for parallel-level inspection, and `quiver:next` for the next ready slice. Use `quiver:graph --format mermaid` for PR-ready Markdown or `quiver:graph --format dot` for Graphviz source.
 Maintain release notes and package publishing with `scripts/release-quiver.sh`.
 The primary generated project context for agents is `docs/AI_CONTEXT.md`.
+The project map is the single source of truth for stack, package manager, commands, and file hints: `docs/PROJECT_MAP.md`.
+The universal router for generated projects is `AGENTS.md`; read it before `docs/AI_CONTEXT.md` and `docs/AI_ONBOARDING_PROMPT.md`.
+Generated projects also get `docs/DECISIONS.md`; use it for durable choices that should not be re-litigated.
 If a generated project has been analyzed, the exact agent handoff prompt is `docs/AI_ONBOARDING_PROMPT.md`.
+If a new bounded transfer is needed, scaffold `specs/<project-slug>/HANDOFF.md` with `npx create-quiver new-handoff <spec-slug>` and validate it with `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md`.
+Use `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md` to validate a transferred handoff before execution.
+During onboarding, after reading `ROADMAP.md`, also read `BACKLOG.md` in the repository root: it tracks emerging patterns that are not yet scoped as specs. Before proposing a new spec, confirm the idea is not already parked or emerging there.
+
+## Token-Efficient Reading Rules
+
+Use the smallest context that still answers the current task.
+
+- **Onboarding:** start from `docs/PROJECT_MAP.md`, `docs/PROJECT_SCAN.json`, `docs/AI_CONTEXT.md`, and `docs/AI_ONBOARDING_PROMPT.md` before opening source files.
+- **Onboarding router:** start from `AGENTS.md` first, then the onboarding files above.
+- **Implementation:** start from `docs/ai/ACTIVE_SLICE.md` when it exists; otherwise start from `specs/<project-slug>/slices/<slice-id>/slice.json`, then read only the declared files, nearby tests, and directly related source.
+- **Handoff:** start from `specs/<project-slug>/HANDOFF.md` when the work was explicitly transferred through a handoff artifact.
+- **Handoff scaffold:** if no handoff exists yet and the work needs one, use `npx create-quiver new-handoff <spec-slug>` first.
+- **Review:** start from `git diff` and the slice scope before opening full files.
+- **Debug:** start from the command, exit code, first relevant error, stacktrace, and the nearest changed code before reading long logs.
+
+Prefer maps, metadata, diffs, and summaries over full file reads when they are enough. Treat front-matter as a skim-first signal: if the header is enough, do not open the body.
 
 ## Core Rules
 
@@ -19,10 +41,17 @@ If a generated project has been analyzed, the exact agent handoff prompt is `doc
 - Always use `init-docs.sh` instead of copying files by hand.
 - Treat `docs-template/` as generic and `docs/` as generated project-specific output.
 - Not every project needs every optional file.
-- The AI context pack lives in `docs/AI_CONTEXT.md`; `docs/CONTEXTO.md` is the broader project overview.
+- The AI context pack lives in `docs/AI_CONTEXT.md`; `docs/CONTEXTO.md` is the broader project overview; `docs/PROJECT_MAP.md` owns stack and command facts.
 - The onboarding prompt lives in `docs/AI_ONBOARDING_PROMPT.md` and should reference the analyzer outputs.
+- `specs/<project-slug>/HANDOFF.md` is reserved for exceptional context transfers between agents or phases.
 - Initial onboarding should complete context docs and report assumptions before any feature work starts.
+- The normal workflow runs from the project root without `--dir`; use `--dir` only when targeting another directory explicitly.
+- The cross-platform work targets native macOS, Linux, and Windows shells; Bash is a legacy compatibility path until the runtime slices land, and Windows support is only considered verified once the CI matrix is green.
 - The support contract lives in `docs/SUPPORT_MATRIX.md` and `docs/TROUBLESHOOTING.md`.
+- Generated project npm scripts should prefer `quiver:*` names such as `quiver:analyze`, `quiver:plan`, `quiver:graph`, `quiver:next`, `quiver:doctor`, `quiver:start-slice`, `quiver:check-slice`, and `quiver:check-pr`.
+- `quiver:graph` defaults to the tree view; choose `--format mermaid` or `--format dot` when you need exportable graph artifacts.
+- `quiver:next` prints the next ready slice and can auto-start it behind a confirmation prompt.
+- `quiver:next --all-ready` prints the whole ready level when you want to inspect every actionable slice at once.
 
 ## Initialization Flow
 
@@ -76,19 +105,22 @@ After initialization, the user should:
 2. Fill in `docs/AI_ONBOARDING_PROMPT.md`
 3. Fill in `docs/CONTEXTO.md`
 4. Fill in `docs/STATUS.md`
-5. Run `npx create-quiver analyze --dir <project>` if scan artifacts are missing
-6. If the project already exists from an older Quiver version, run `npx create-quiver migrate --dir <project>`
-7. Ask the AI agent to execute `docs/AI_ONBOARDING_PROMPT.md`
-8. Review context docs before creating the first implementation slice
-9. Open and merge the documentation PR that establishes the workflow files
-10. Create the first slice in `specs/{{PROJECT_SLUG}}/slices/[slice-id]/`
-11. Add `ticket` and `git.*`
-12. Run `tools/scripts/start-slice.sh [--allow-draft] <slice.json>`
-13. Make one commit per slice
-14. Open one PR per spec
-15. Validate the slice and the final PR with the workflow gates
-
-Bootstrap note: `start-slice.sh` should resolve paths canonically, prefer a local `develop` or `main` base branch before reaching for `origin`, and reject `draft` slices unless `--allow-draft` is passed intentionally.
+5. Run `npx create-quiver analyze` if scan artifacts are missing
+6. If the project already exists from an older Quiver version and was previously initialized by Quiver, run `npx create-quiver migrate`
+7. If the project was never initialized by Quiver, run `npx create-quiver --name "Project Name"` instead of `migrate`
+8. Ask the AI agent to execute `docs/AI_ONBOARDING_PROMPT.md`
+9. Review context docs before creating the first implementation slice
+10. Open and merge the documentation PR that establishes the workflow files
+11. Create the first slice in `specs/{{PROJECT_SLUG}}/slices/[slice-id]/`
+12. Add `ticket` and `git.*`
+13. Run `npx create-quiver plan` or `npm run quiver:plan`
+14. Run `npx create-quiver next` or `npm run quiver:next`
+14. Run `npx create-quiver start-slice [--allow-draft] <slice.json>` or `npm run quiver:start-slice -- [--allow-draft] <slice.json>`
+15. Make one commit per slice
+16. Open one PR per spec
+17. Validate the slice and the final PR with the workflow gates
+
+Bootstrap note: `start-slice` should resolve paths canonically, prefer a local `develop` or `main` base branch before reaching for `origin`, and reject `draft` slices unless `--allow-draft` is passed intentionally.
 
 ## Optional Files
 

package/ROADMAP.md

@@ -18,3 +18,103 @@
 - Add richer templates and examples
 - Improve release workflows
 
+## v0.4 (shipped 2026-04-21)
+
+- `create-quiver` CLI installer surface
+- Post-init `doctor` validation mode
+- Release helper and packaged-installer smoke checks
+
+## v0.5 (shipped)
+
+- Existing project migration flow (`create-quiver migrate`)
+- Onboarding README flow polish
+- Local project installation guidance
+
+## v0.6 (shipped)
+
+> Scope absorbed into v0.7. Node-native runtime and `quiver:*` npm scripts
+> landed together with the token-efficient context pack work.
+
+- Cross-platform CI matrix (macOS, Linux, Windows) for Node-native runtime
+- Node-native generated project npm scripts (`quiver:*`)
+- Additive migration support for existing projects
+
+## v0.7 — Token-Efficient AI Context Packs (shipped 2026-04-23)
+
+- **v13** — Token-efficient AI modes guidance (Completed)
+- **v14** — Tiered context pack: QUICK/STANDARD/DEEP tiers, AGENTS.md router, ACTIVE_SLICE lifecycle, YAML front-matter, dedup (Completed)
+- **v15** — Init required before migrate (Completed)
+- v13 slice-04 reconciled into v14 slice-05 (2026-04-23); v13 slice-02 narrowed to `DECISIONS.md` only
+- Validation checkpoint passed after real-world use and spec completion
+
+## Post-Checkpoint Plan (do not execute before validating v14)
+
+> This section is intentionally speculative. Every item below is pending
+> evidence from v14 in real use. Rescope or drop anything that does not
+> respond to observed friction.
+
+### Orchestration and Tooling (v19–v22, spec drafts created 2026-04-23)
+
+Draft specs exist but are **not executed until v18 passes its validation checkpoint**. Each subsequent spec requires the previous one to pass its own checkpoint before it starts.
+
+- **v19 — Project Visibility** (3 slices, ~11h): `quiver:status`, `quiver:estimate`, `quiver:lint-spec`
+- **v20 — Context Diagnostics** (3 slices, ~13h): `quiver:cost`, `quiver:diff-pack`, `quiver:replay`
+- **v21 — Slice Archaeology** (2 slices, ~7h): `quiver:archive`, `quiver:blame-slice`; `bisect-slice` documented via `git bisect run` in TROUBLESHOOTING
+- **v22 — Deferred Tooling** (3 slices, ~10h, evidence-gated): `quiver:fork-slice`, `quiver:squash-spec`, `quiver:share`
+
+Plan total: ~41h across 11 slices. Drafts parked on `drafts/v19-v22-orchestration-followups`. v22 stays deferred until BACKLOG.md records ≥1 occurrence per slice.
+
+### v0.8 — Handoff Contract (draft spec created, pending evidence)
+
+- Canonical `HANDOFF.md.template` for exceptional context transfers
+- `create-quiver check-handoff <path>` validation for structure and placement
+- Optional `create-quiver new-handoff <slug>` scaffold
+- Keep handoffs orthogonal to `slice.json`, not a new slice type
+
+### v0.9 — Context Hygiene and Diagnostics (proposed, not yet spec-ed)
+
+- Analyzer noise filter (ignore lockfiles, dist/, build/, binaries, generated files)
+- `create-quiver token-cost` diagnostic (4 chars/token heuristic)
+- `create-quiver diff-pack` for review and debug modes
+- Cache-friendly ordering within the pack (stable above, volatile below)
+- `docs/ai/INDEX.yaml` inverted index (directory → purpose)
+
+### Block A — Zero-Question First Use (proposed)
+
+- `npx create-quiver` with no args auto-detects name, stack, runs analyze + doctor
+- `--lite` template variant for small projects
+- Optional `--interactive` wizard
+- Auto-regenerate context pack on every `start-slice`
+
+### Block B — Multi-Model Context Adapters (proposed, only if users ask)
+
+- Additional adapters beyond `AGENTS.md`: `.cursorrules`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, `PROMPT_FOR_EXECUTOR.md`
+- Decision driven by which tools actual users adopt
+
+### Block C — Convincing Example (proposed)
+
+- Real end-to-end example in `examples/full-crud/` with 3 merged slices
+- 30-second hello-world asciinema at top of README
+- "When NOT to use Quiver" section
+
+### Block D — Polish Debt (proposed)
+
+- Actionable error messages (replace stack traces)
+- Embedded JSON Schema validation for `slice.json`
+- `start-slice` without arguments auto-detects active slice by branch
+- `create-quiver status` dashboard
+
+### Deferred Until Real Demand
+
+- Killing Bash entirely (breaking change — needs user base first)
+- `@quiver/cli` / `@quiver/template` package split
+- Git hooks auto-install
+- Metrics/telemetry
+
+## Decision Rules
+
+- No new spec is written until the previous spec's checkpoint passes
+- Specs respond to observed friction, not pre-planned lists
+- Breaking changes require at least one confirmed external user
+- Prefer recording "we decided not to do X" over silently dropping ideas
+- Emerging patterns that are not yet ready for a spec live in [`BACKLOG.md`](./BACKLOG.md) — review it before writing a new spec