create-quiver 0.7.0 → 0.9.0

package/.claude/settings.local.json

@@ -0,0 +1,52 @@
+{
+  "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 *)",
+      "Bash(rm -rf /tmp/quiver-skip-test)",
+      "Bash(mkdir -p /tmp/quiver-skip-test)",
+      "Bash(echo '{\"name\":\"test\",\"scripts\":{}}')",
+      "Bash(ls /tmp/quiver-skip-test/node_modules/create-quiver)",
+      "Bash(rm -rf /tmp/quiver-install-test)",
+      "Bash(mkdir -p /tmp/quiver-install-test)",
+      "Bash(npm config *)"
+    ]
+  }
+}

package/.github/workflows/ci.yml

@@ -22,8 +22,8 @@ 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'))"
 
   cross-platform-smoke:
     strategy:

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,11 +4,30 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-05-14
+
 ### Added
 
-- Cross-platform CI matrix covering macOS, Linux, and Windows for the Node-native Quiver runtime
+- Auto-install `create-quiver` as a dev dependency after `init` and `migrate` — detects yarn/pnpm/bun/npm via lockfiles and runs the appropriate install command
+- `--skip-install` flag to suppress the dev dependency install step (useful for CI environments)
+
+## [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

@@ -38,14 +38,19 @@ Run the local analyzer and then validate the generated contract from the project
 
 ```bash
 npx create-quiver analyze
+npx create-quiver graph
 npx create-quiver doctor
+npx create-quiver next
 ```
 
+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` first.
+`npx create-quiver next` prints the next ready slice and can auto-start it behind a confirmation prompt.
 
 ### Project NPM Scripts
 
@@ -53,6 +58,9 @@ Generated projects include `quiver:*` npm scripts that call the Node CLI and are
 
 ```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
@@ -63,7 +71,12 @@ 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
 
@@ -73,7 +86,17 @@ If the project already had Quiver from an older version, upgrade it from the pro
 cd /path/to/your-project
 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:
@@ -82,9 +105,12 @@ If your team prefers a pinned local dependency, update the package first and the
 npm install --save-dev create-quiver@latest
 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:
@@ -130,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
@@ -146,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

@@ -8,14 +8,17 @@ Important: slice numbering resets inside each spec. `slice-01` is the first slic
 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` from the project root.
-If the project already exists from an older Quiver version, run `npx create-quiver migrate` before `analyze` from the project root.
-Generated projects also get `quiver:*` npm scripts that call the Node CLI directly; prefer those for repeatable project workflows.
+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
@@ -25,6 +28,8 @@ 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.
 
@@ -38,11 +43,15 @@ Prefer maps, metadata, diffs, and summaries over full file reads when they are e
 - 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; `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:doctor`, `quiver:start-slice`, `quiver:check-slice`, and `quiver:check-pr`.
+- 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
 
@@ -97,16 +106,19 @@ After initialization, the user should:
 3. Fill in `docs/CONTEXTO.md`
 4. Fill in `docs/STATUS.md`
 5. Run `npx create-quiver analyze` if scan artifacts are missing
-6. If the project already exists from an older Quiver version, run `npx create-quiver migrate`
-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 `npx create-quiver start-slice [--allow-draft] <slice.json>` or `npm run quiver:start-slice -- [--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
+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.
 

package/ROADMAP.md

@@ -30,18 +30,22 @@
 - Onboarding README flow polish
 - Local project installation guidance
 
-## v0.6 (unreleased)
+## 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 (in progress)
+## v0.7 — Token-Efficient AI Context Packs (shipped 2026-04-23)
 
-- **v13** — Token-efficient AI modes guidance (Draft)
-- **v14** — Tiered context pack: QUICK/STANDARD/DEEP tiers, AGENTS.md router, ACTIVE_SLICE lifecycle, YAML front-matter, dedup (Draft, 5 slices)
+- **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** — 1 week real-world use + ≥1 external user before v15 is scoped
+- Validation checkpoint passed after real-world use and spec completion
 
 ## Post-Checkpoint Plan (do not execute before validating v14)
 
@@ -49,7 +53,25 @@
 > evidence from v14 in real use. Rescope or drop anything that does not
 > respond to observed friction.
 
-### v15 — Context Hygiene and Diagnostics (proposed, not yet spec-ed)
+### 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)

package/docs/AI_ONBOARDING_PROMPT.md.template

@@ -15,12 +15,16 @@ You are the onboarding agent for this project. Your job is to analyze the genera
 6. `specs/{{PROJECT_SLUG}}/SPEC.md`
 7. `specs/{{PROJECT_SLUG}}/STATUS.md`
 8. `specs/{{PROJECT_SLUG}}/EVIDENCE_REPORT.md`
+9. `specs/{{PROJECT_SLUG}}/HANDOFF.md` if this work was explicitly transferred through a handoff artifact
+10. `npx create-quiver new-handoff <spec-slug>` if a new handoff artifact needs to be scaffolded before validation
 
 ## Mission
 
 - Use the analyzer outputs to understand the repository instead of guessing.
 - Treat `docs/PROJECT_MAP.md` as the single source of truth for stack, package manager, commands, and file hints.
 - Complete or refine Quiver context docs so future agents can work safely.
+- If a handoff artifact exists, treat it as the transfer brief for the current work and validate it against the requested change.
+- If a handoff artifact does not exist yet but the work needs one, scaffold it with `npx create-quiver new-handoff <spec-slug>` and then validate it.
 - Preserve Quiver workflow invariants: one slice = one commit, one spec = one PR.
 - Ask for confirmation before making product-code changes.
 

package/docs/COMMANDS.md.template

@@ -0,0 +1,25 @@
+# Commands
+
+**Project:** {{PROJECT_NAME}}
+**Last updated:** {{FECHA}}
+
+This document is the canonical command reference for the orchestration roadmap.
+It is intentionally small at v0.18: only the plan and graph rows are reserved for now, but `quiver:graph` already supports tree, Mermaid, and DOT output modes.
+
+## Command Table
+
+| Command | Purpose | OS | Since | Example |
+|---------|---------|----|-------|---------|
+| `quiver:plan` | Sequential orchestration planning command | macOS, Linux, Windows | v0.18 | [docs/examples/plan.md](./examples/plan.md) |
+| `quiver:graph` | Parallel-level orchestration tree command | macOS, Linux, Windows | v0.18 | [docs/examples/graph.md](./examples/graph.md) |
+| `quiver:next` | Ready-slice suggestion command | macOS, Linux, Windows | v0.18 | [docs/examples/next.md](./examples/next.md) |
+
+## Notes
+
+- Add new rows here only when a command is officially shipped.
+- Keep the table concise and cross-platform.
+- Shared graph library: `src/create-quiver/lib/slice-graph.js`.
+- `quiver:graph --format mermaid` is the PR-friendly export; `--format dot` is for Graphviz consumers.
+- `quiver:next` prints the next ready slice and can auto-start it behind a confirmation prompt.
+- `check-slice` now validates optional `depends_on` targets and requires `parallel_safe_reason` when `parallel_safe` is set to `never`.
+- Cross-platform authoring rules live in `docs/SUPPORT_MATRIX.md`.

package/docs/INDEX.md.template

@@ -10,6 +10,7 @@
 - **Decision Log** - `./DECISIONS.md`
 - **AI Onboarding Prompt** - `./AI_ONBOARDING_PROMPT.md`
 - **Workflow** - `./WORKFLOW.md`
+- **Commands** - `./COMMANDS.md`
 - **Support Matrix** - `./SUPPORT_MATRIX.md`
 - **Troubleshooting** - `./TROUBLESHOOTING.md`
 - **Multi-agent workflow** - `./MULTI_AGENT_WORKFLOW.md`
@@ -44,6 +45,7 @@ docs/
 ├── CONTEXTO.md
 ├── STATUS.md
 ├── WORKFLOW.md
+├── COMMANDS.md
 ├── SUPPORT_MATRIX.md
 ├── TROUBLESHOOTING.md
 ├── MULTI_AGENT_WORKFLOW.md

package/docs/SUPPORT_MATRIX.md.template

@@ -17,6 +17,15 @@ Quiver is intentionally opinionated about the first-run environment. If your set
 | Worktree state | Clean worktree | Slice execution and PR checks expect no unrelated local changes. |
 | Path handling | Canonical filesystem paths | Use the physical path to the repo and slice files, not a symlinked alias. |
 
+## Cross-Platform Authoring Rules
+
+- No shell invocations for logic: use Node.js `fs`, `path`, and `child_process` with `shell: false`.
+- Build paths with `path.join` and `path.sep`; normalize to `/` only for human-readable output.
+- Write files with `\n`; read files tolerating `\r\n`.
+- `--json` is the primary contract; human output is courtesy and may vary.
+- Colors are TTY-aware and suppressed with `NO_COLOR`; Unicode is opt-in unless UTF-8 is available.
+- Optional external tools such as `gh` and `graphviz` should be probed and skipped gracefully if missing.
+
 ## Remote Modes
 
 | Mode | Supported | Notes |

package/docs/WORKFLOW.md.template

@@ -16,11 +16,15 @@ This document is the canonical implementation workflow for the project.
 - The support matrix defines the supported OS, git, node, and remote modes.
 - The troubleshooting guide explains the first-run recovery paths for common bootstrap failures.
 - The AI onboarding prompt generated after analysis is the handoff for agents that need project context before editing.
+- `specs/<project-slug>/HANDOFF.md` is the exceptional transfer artifact for agents or phases that need bounded context handoff.
+- Scaffold a new handoff only when needed with `npx create-quiver new-handoff <spec-slug>`, then validate it with `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md`.
 
 ## Mode-Aware Context Selection
 
 - **Onboarding:** read `PROJECT_SCAN.json`, `PROJECT_MAP.md`, `AI_CONTEXT.md`, and `AI_ONBOARDING_PROMPT.md` before source files.
 - **Implementation:** read `docs/ai/ACTIVE_SLICE.md` first when it exists; otherwise read `slice.json`, declared files, nearby tests, and only then adjacent source.
+- **Handoff:** read `specs/<project-slug>/HANDOFF.md` when the work was explicitly transferred through a handoff artifact.
+- Validate a received handoff with `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md` before starting execution.
 - **Review:** read `git diff` and the slice scope before opening full files.
 - **Debug:** read the command, exit code, first relevant error, stacktrace, and nearest changed code before long logs.
 

package/docs/examples/graph.md.template

@@ -0,0 +1,62 @@
+# Graph Example
+
+Use `graph` to inspect the parallel levels and conflict groups before starting implementation work. The default tree view is best for humans, Mermaid is best for PR descriptions, and DOT is best for Graphviz pipelines.
+
+## Input
+
+```bash
+npx create-quiver graph --show-conflicts
+npx create-quiver graph --format mermaid --show-conflicts
+npx create-quiver graph --format dot --show-conflicts
+```
+
+## Representative Output
+
+### Tree
+
+```text
+Quiver graph
+Level 0 (2 slices, 2 lots)
++-- spec-a/slice-01-alpha Alpha [draft]
+\-- spec-b/slice-01-beta Beta [draft]
+|
+Level 1 (2 slices, 1 lots)
++-- ! spec-c/slice-02-gamma Gamma [draft] [docs/shared.md]
+\-- ! spec-d/slice-02-delta Delta [draft] [docs/shared.md]
+```
+
+### Mermaid
+
+```mermaid
+flowchart TD
+  n_spec_a_slice_01_alpha["spec-a/slice-01-alpha<br/>Alpha<br/>2h<br/>[draft]"]
+  n_spec_b_slice_01_beta["spec-b/slice-01-beta<br/>Beta<br/>3h<br/>[draft]"]
+  n_spec_c_slice_02_gamma["! spec-c/slice-02-gamma<br/>Gamma<br/>4h<br/>[draft]<br/>Files: docs/shared.md"]
+  n_spec_d_slice_02_delta["! spec-d/slice-02-delta<br/>Delta<br/>1h<br/>[draft]<br/>Files: docs/shared.md"]
+  n_spec_a_slice_01_alpha --> n_spec_c_slice_02_gamma
+  n_spec_b_slice_01_beta --> n_spec_d_slice_02_delta
+```
+
+### DOT
+
+```dot
+digraph QuiverGraph {
+  rankdir=TB;
+  node [shape=box, style="rounded,filled", fillcolor="#f8f9fa", color="#495057", fontname="Helvetica"];
+  edge [color="#6c757d"];
+  n_spec_a_slice_01_alpha [label="spec-a/slice-01-alpha\nAlpha\n2h\n[draft]"];
+  n_spec_b_slice_01_beta [label="spec-b/slice-01-beta\nBeta\n3h\n[draft]"];
+  n_spec_c_slice_02_gamma [label="! spec-c/slice-02-gamma\nGamma\n4h\n[draft]\nFiles: docs/shared.md", fillcolor="#fff3cd", color="#d39e00"];
+  n_spec_d_slice_02_delta [label="! spec-d/slice-02-delta\nDelta\n1h\n[draft]\nFiles: docs/shared.md", fillcolor="#fff3cd", color="#d39e00"];
+  n_spec_a_slice_01_alpha -> n_spec_c_slice_02_gamma;
+  n_spec_b_slice_01_beta -> n_spec_d_slice_02_delta;
+}
+```
+
+## Notes
+
+- GitHub renders Mermaid fenced blocks directly in markdown.
+- DOT output is plain source; render it with Graphviz if you want an image.
+- The exact level grouping depends on the repo's pending dependency graph.
+- Use `--level <n>` to focus on a single level.
+- Use `--json` when another tool needs structured levels and conflict groups.