create-quiver 0.6.0 → 0.8.0

package/docs/AI_CONTEXT.md.template

@@ -1,9 +1,6 @@
 # {{PROJECT_NAME}} AI Context Pack
 
-**Date:** {{FECHA}}
-**Status:** {{ESTADO}}
-
-This file is the first stop for any AI agent working in this project. It compresses the working contract into one place and points to the canonical docs when deeper context is required.
+This file is the main context pack after `AGENTS.md` and `docs/PROJECT_MAP.md`. It compresses the working contract into one place and points to the canonical docs when deeper context is required.
 
 ## What This Project Is
 
@@ -11,14 +8,23 @@ This file is the first stop for any AI agent working in this project. It compres
 
 ## Read First
 
-1. `docs/INDEX.md`
-2. `docs/AI_CONTEXT.md`
-3. `docs/CONTEXTO.md`
-4. `docs/WORKFLOW.md`
-5. `docs/SUPPORT_MATRIX.md`
-6. `docs/TROUBLESHOOTING.md`
-7. `specs/{{PROJECT_SLUG}}/SPEC.md`
-8. `specs/{{PROJECT_SLUG}}/slices/[slice-id]/slice.json`
+1. `docs/PROJECT_MAP.md`
+2. `docs/INDEX.md`
+3. `docs/AI_ONBOARDING_PROMPT.md`
+4. `docs/DECISIONS.md`
+5. `docs/CONTEXTO.md`
+6. `docs/WORKFLOW.md`
+7. `docs/SUPPORT_MATRIX.md`
+8. `docs/TROUBLESHOOTING.md`
+9. `specs/{{PROJECT_SLUG}}/SPEC.md`
+10. `specs/{{PROJECT_SLUG}}/slices/[slice-id]/slice.json`
+
+## Why This Pack Exists
+
+- Project Map: `docs/PROJECT_MAP.md` is the single source of truth for stack, package manager, commands, and file hints.
+- `docs/AI_ONBOARDING_PROMPT.md` is the handoff after analysis.
+- `docs/DECISIONS.md` tracks durable choices so agents do not re-litigate them.
+- `docs/STATUS.md` tracks progress, blockers, and the current slice.
 
 ## Critical Rules
 
@@ -30,19 +36,6 @@ This file is the first stop for any AI agent working in this project. It compres
 - Never overwrite user-authored content without checking whether the file is meant to be preserved.
 - If a command or path is ambiguous, prefer the local project root and the generated docs.
 
-## Common Commands
-
-```bash
-cd /path/to/project
-npx create-quiver --name "Project Name"
-npx create-quiver migrate --dir .
-npx create-quiver analyze --dir .
-npx create-quiver doctor --dir .
-bash tools/scripts/start-slice.sh <slice.json>
-bash tools/scripts/check-slice-readiness.sh <slice.json>
-bash tools/scripts/check-pr-readiness.sh <slice.json>
-```
-
 ## What To Update After A Slice
 
 - `specs/{{PROJECT_SLUG}}/STATUS.md`
@@ -52,7 +45,7 @@ bash tools/scripts/check-pr-readiness.sh <slice.json>
 
 ## If You Need More Context
 
-Read `docs/CONTEXTO.md` for the human project overview and `docs/WORKFLOW.md` for the execution contract.
+Read `docs/DECISIONS.md` for durable choices, `docs/CONTEXTO.md` for the human project overview, and `docs/WORKFLOW.md` for the execution contract. When you need stack details or command references, open `docs/PROJECT_MAP.md`.
 
 ## If The Environment Fails
 

package/docs/AI_ONBOARDING_PROMPT.md.template

@@ -15,14 +15,30 @@ 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.
 
+## Mode Selection
+
+Use the least context that still solves the task:
+
+- **Onboarding:** rely on maps and metadata first. Read `docs/PROJECT_SCAN.json` and `docs/PROJECT_MAP.md` before any source files, then use `docs/AI_CONTEXT.md` and `docs/CONTEXTO.md` to fill gaps.
+- **Implementation:** start from `specs/{{PROJECT_SLUG}}/slices/<slice-id>/slice.json`, then read the declared files, nearby tests, and only then adjacent source.
+- **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 summaries, deltas, and metadata over full file reads when they are sufficient.
+
 ## Hard Constraints
 
 - Do not read or expose secret values from `.env`, credential files, tokens, SSH keys, or private config.

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/CONTEXTO.md.template

@@ -1,8 +1,5 @@
 # {{PROJECT_NAME}} Context
 
-**Date:** {{FECHA}}
-**Status:** {{ESTADO}}
-
 ## What Is {{PROJECT_NAME}}?
 
 [One or two paragraphs that explain the project.]
@@ -15,25 +12,15 @@
 
 [Describe the primary user.]
 
-## Technical Stack
-
-```text
-Frontend:
-├── [Framework]
-├── [Language]
-└── [UI library]
-
-Backend:
-├── [Framework]
-├── [Database]
-└── [Deploy target]
-```
-
 ## Current Focus
 
 - [Current goal 1]
 - [Current goal 2]
 
+## Where The Stack Lives
+
+The stack, package manager, and command surface are generated in `docs/PROJECT_MAP.md` after analysis. Keep this file focused on the human summary.
+
 ## Security and Privacy
 
 - [Sensitive data that is never stored]

package/docs/DECISIONS.md.template

@@ -0,0 +1,18 @@
+# {{PROJECT_NAME}} Decision Log
+
+**Date:** {{FECHA}}
+**Status:** {{ESTADO}}
+
+This file records durable project decisions so AI agents do not re-litigate choices that were already made.
+
+## Log
+
+| Date | Decision | Reason | Alternatives | Impact |
+|------|----------|--------|--------------|--------|
+
+## Rules
+
+- Record one decision per row.
+- Keep entries short and specific.
+- Prefer the decision outcome, not the full discussion history.
+- Add a new row when a choice would otherwise be re-opened during future work.

package/docs/DEEP.md.template

@@ -0,0 +1,34 @@
+# {{PROJECT_NAME}} Deep Context
+
+**Date:** {{FECHA}}
+**Status:** {{ESTADO}}
+
+Use this file for history, decisions, and context that does not belong in the default pack.
+
+## What Belongs Here
+
+- Project history and major milestones
+- Durable decisions that explain why the workflow exists
+- Cultural notes and team preferences
+- Legacy migrations and compatibility caveats
+- Edge cases that keep coming back
+
+## What Not To Repeat
+
+- Do not duplicate `docs/QUICK.md`
+- Do not duplicate `docs/STANDARD.md`
+- Do not restate stack or command tables; link to `docs/PROJECT_MAP.md`
+- Keep the deep pack additive, not repetitive
+
+## Suggested Sections
+
+- Background
+- Key Decisions
+- Migration Notes
+- Open Questions
+- Lessons Learned
+- Archived Context
+
+## Notes
+
+Add longer narratives only when they help future planning models avoid re-discovering old decisions.

package/docs/DOCUMENTATION_GUIDE.md.template

@@ -7,13 +7,14 @@
 
 1. `docs/INDEX.md`
 2. `docs/AI_CONTEXT.md`
-3. `docs/CONTEXTO.md`
-4. `docs/STATUS.md`
-5. `docs/WORKFLOW.md`
-6. `docs/SUPPORT_MATRIX.md`
-7. `docs/TROUBLESHOOTING.md`
-8. `specs/{{PROJECT_SLUG}}/SPEC.md`
-9. `specs/{{PROJECT_SLUG}}/slices/[slice-id]/slice.json`
+3. `docs/DECISIONS.md`
+4. `docs/CONTEXTO.md`
+5. `docs/STATUS.md`
+6. `docs/WORKFLOW.md`
+7. `docs/SUPPORT_MATRIX.md`
+8. `docs/TROUBLESHOOTING.md`
+9. `specs/{{PROJECT_SLUG}}/SPEC.md`
+10. `specs/{{PROJECT_SLUG}}/slices/[slice-id]/slice.json`
 
 ## Update Rules
 
@@ -25,6 +26,7 @@
 
 - Project overview: `docs/CONTEXTO.md`
 - Agent context pack: `docs/AI_CONTEXT.md`
+- Decisions: `docs/DECISIONS.md`
 - Progress: `docs/STATUS.md`
 - Implementation workflow: `docs/WORKFLOW.md`
 - Support contract: `docs/SUPPORT_MATRIX.md`

package/docs/GITFLOW_PR_GUIDE.md.template

@@ -16,6 +16,13 @@ This guide explains how to open and review spec PRs without breaking the canonic
 - Open and merge the documentation PR before the first slice starts execution
 - Do not open the spec PR before the documentation PR is merged
 
+## Review Guidance
+
+- Start with `git diff` and the slice scope before opening full files.
+- Use the diff to confirm what changed, then open full files only for gaps, regressions, or unclear context.
+- For debugging reviews, inspect the first relevant error, stacktrace, or failing command before reading large logs.
+- Keep review notes anchored to the changed lines and the slice acceptance criteria.
+
 ## Required PR Headings
 
 All spec PR notes must use:

package/docs/INDEX.md.template

@@ -4,16 +4,22 @@
 
 ## Start Here
 
+- **Project Map** - `./PROJECT_MAP.md`
 - **Context** - `./CONTEXTO.md`
 - **AI Context** - `./AI_CONTEXT.md`
+- **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`
 
 ## AI Configuration
 
+- **QUICK** - `./ai/QUICK.md`
+- **STANDARD** - `./ai/STANDARD.md`
+- **DEEP** - `./ai/DEEP.md`
 - **Principles** - `./ai/PRINCIPLES.md`
 - **Rules** - `./ai/RULES.yaml`
 - **Lessons** - `./ai/LESSONS.md`
@@ -31,10 +37,15 @@
 docs/
 ├── INDEX.md
 ├── AI_CONTEXT.md
+├── DECISIONS.md
+├── ai/QUICK.md
+├── ai/STANDARD.md
+├── ai/DEEP.md
 ├── AI_ONBOARDING_PROMPT.md
 ├── CONTEXTO.md
 ├── STATUS.md
 ├── WORKFLOW.md
+├── COMMANDS.md
 ├── SUPPORT_MATRIX.md
 ├── TROUBLESHOOTING.md
 ├── MULTI_AGENT_WORKFLOW.md

package/docs/QUICK.md.template

@@ -0,0 +1,27 @@
+# {{PROJECT_NAME}} Quick Context
+
+Minimum viable briefing for execution agents.
+
+## Snapshot
+
+- Project: {{PROJECT_NAME}}
+- Project map: `docs/PROJECT_MAP.md`
+- Focus: unknown until analyze
+
+## Where Commands Live
+
+Use `docs/PROJECT_MAP.md` for the package manager, project stack, test commands, and Quiver command surface.
+
+## Hard Rules
+
+- One slice = one commit.
+- One spec = one PR.
+- Read `./STANDARD.md` for workflow details.
+- Read `./DEEP.md` for history and context.
+- Do not edit files outside the active slice.
+- Prefer project-root commands over global installs.
+
+## Read Next
+
+- `./STANDARD.md`
+- `./DEEP.md`

package/docs/STANDARD.md.template

@@ -0,0 +1,49 @@
+# {{PROJECT_NAME}} Standard Context
+
+**Date:** {{FECHA}}
+**Status:** {{ESTADO}}
+
+This is the default context pack for everyday AI work.
+
+## Reading Order
+
+1. `./QUICK.md`
+2. `docs/PROJECT_MAP.md`
+3. `docs/AI_CONTEXT.md`
+4. `docs/DECISIONS.md`
+5. `docs/CONTEXTO.md`
+6. `docs/WORKFLOW.md`
+
+## Conventions
+
+- Use maps, metadata, and diffs before opening full source files.
+- Keep scope inside the active slice.
+- Make one commit per slice.
+- Open one PR per spec.
+- Record durable decisions in `docs/DECISIONS.md`.
+- Treat `docs/PROJECT_MAP.md` as the single source of truth for stack, package manager, and command references.
+
+## Workflow Overview
+
+- Onboarding starts from `docs/PROJECT_SCAN.json` and `docs/PROJECT_MAP.md`.
+- Implementation starts from `specs/{{PROJECT_SLUG}}/slices/<slice-id>/slice.json`.
+- Review starts from `git diff` and the slice scope.
+- Debugging starts from the command, exit code, first relevant error, and stacktrace.
+
+## Testing Expectations
+
+- Validate the active slice before merging.
+- Prefer focused smoke tests over large manual walkthroughs.
+- Preserve existing user-authored content during migration.
+- Keep secret-safe paths and generated heavy folders out of the read path.
+
+## V13 Mode Guidance
+
+- Onboarding: read maps and metadata first.
+- Implementation: read `slice.json` and declared files first.
+- Review: inspect `git diff` before full files.
+- Debug: inspect the error signal before long logs.
+
+## Read Next
+
+- `./DEEP.md`

package/docs/STATUS.md.template

@@ -1,7 +1,6 @@
 # {{PROJECT_NAME}} Status
 
-**Last updated:** {{FECHA}}
-**Next update:** {{FECHA_PROXIMA}}
+This page tracks progress, blockers, and the current slice. Stack and command details live in `docs/PROJECT_MAP.md`.
 
 ## Overall Status
 
@@ -24,3 +23,4 @@
 ## Notes
 
 - Update this file after each completed slice.
+- Keep stack and command changes in `docs/PROJECT_MAP.md`, not here.

package/docs/SUPPORT_MATRIX.md.template

@@ -9,13 +9,23 @@ Quiver is intentionally opinionated about the first-run environment. If your set
 
 | Area | Supported | Notes |
 |------|-----------|-------|
-| Operating systems | macOS and Linux | Windows is not supported in this workflow. |
-| Git | Git 2.40+ | Must support worktrees and standard branch refs. |
-| Node.js | Node 22.x LTS | Used for date handling and JSON validation. |
+| Operating systems | macOS, Linux, and Windows | Windows native support is verified only when the cross-platform CI matrix is green. |
+| Shells | Terminal, bash-compatible shells, PowerShell, and CMD | Bash is a legacy compatibility path, not a required runtime dependency. |
+| Git | Git 2.40+ | Must support worktrees and standard branch refs on every supported OS. |
+| Node.js | Node 22.x LTS | Required on every supported OS. |
 | Base branches | `develop` or `main` | Local base branches are preferred; `origin` is optional. |
 | 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 |
@@ -26,6 +36,8 @@ Quiver is intentionally opinionated about the first-run environment. If your set
 
 ## What This Means
 
-- You can bootstrap a slice on macOS or Linux without changing the scripts.
+- You can bootstrap and run Quiver on macOS, Linux, and Windows native shells once the runtime slices land and the CI matrix is green.
+- Windows native usage should target PowerShell or CMD instead of Bash.
+- Quiver should not auto-install Bash, Git Bash, MSYS2, or WSL.
 - You do not need a remote to begin work if a local base branch already exists.
 - If the environment is outside the matrix, fix the machine first instead of working around the scripts.

package/docs/TESTING_GUIDE_FOR_AI.md.template

@@ -31,9 +31,10 @@
 
 ## Evidence
 
-- Logs
-- Screenshots
-- Diff output
+- Prefer summarized command evidence over pasted long logs.
+- Capture the command, exit code, first relevant error, and stacktrace when available.
+- Record the log path or artifact path instead of dumping full logs inline.
+- Use screenshots or diff output only when they are the smallest useful proof.
 
 ## If Something Fails
 

package/docs/TROUBLESHOOTING.md.template

@@ -68,3 +68,17 @@ Use this guide when a first-run bootstrap or gate check fails. The recovery path
 1. Commit or stash unrelated changes first.
 2. Re-run the gate from the slice branch.
 3. Make sure the PR body lives in `pr.md` beside the slice.
+
+## Windows Shell Fallback
+
+### Symptom
+
+- You are on Windows and the cross-platform runtime is not yet verified by CI
+- A command expects a Bash-compatible shell before the cross-platform port is complete
+
+### Recovery
+
+1. Prefer PowerShell or CMD once the native runtime slices and CI matrix are complete.
+2. If you are using an intermediate build and need a temporary bridge, use WSL2 or Git Bash manually.
+3. Do not expect Quiver to install Bash, WSL, or MSYS2 for you.
+4. Re-run the command after the cross-platform support slices are merged and the CI matrix is green.

package/docs/WORKFLOW.md.template

@@ -16,6 +16,19 @@ 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.
+
+Use maps, metadata, diffs, and summaries first. Open full files only when the smaller context is not enough.
 
 ## Planning
 
@@ -27,21 +40,25 @@ This document is the canonical implementation workflow for the project.
 6. Read the AI context pack, support matrix, and troubleshooting guide before the first slice if the environment is new or uncertain.
 7. If the project already existed before this Quiver version, run `migrate` before `analyze`.
 8. If the project was analyzed, read `AI_ONBOARDING_PROMPT.md` before making documentation updates.
+9. Prefer the generated `quiver:*` npm scripts for repeatable project workflows once the package has been initialized or migrated.
 
 ## Execution
 
-1. Bootstrap the slice with `start-slice.sh`.
+1. Bootstrap the slice with `npx create-quiver start-slice <slice.json>` or `npm run quiver:start-slice -- <slice.json>`.
    - The bootstrap step should work with canonical paths and a local base branch when `origin` is absent.
-   - Draft slices require `--allow-draft`; otherwise `start-slice.sh` exits before execution.
+   - Draft slices require `--allow-draft`; otherwise `npx create-quiver start-slice` exits before execution.
+   - Legacy Bash wrappers remain available for compatibility, but generated projects should prefer the Node CLI and `quiver:*` npm scripts.
+   - `start-slice` generates `docs/ai/ACTIVE_SLICE.md` and `WORKTREE_CONTEXT.md`; use the active slice brief as the source of truth for execution.
 2. Implement only what the slice declares.
 3. Make one commit for that slice.
-4. Validate with `check-slice-readiness.sh`.
+4. Validate with `npx create-quiver check-slice <slice.json>` or `npm run quiver:check-slice -- <slice.json>`.
 5. Write evidence.
 6. Repeat for the next slice until the spec is complete.
-7. Open one PR for the spec and use `check-pr-readiness.sh` as the pre-merge gate.
+7. Open one PR for the spec and use `npx create-quiver check-pr <slice.json>` or `npm run quiver:check-pr -- <slice.json>` as the pre-merge gate.
 
 ## Support Contract
 
+- `docs/PROJECT_MAP.md` is the source of truth for stack, package manager, and commands.
 - Support Matrix (`SUPPORT_MATRIX.md`) documents what is supported.
 - AI Context Pack (`AI_CONTEXT.md`) gives the agent-first project snapshot.
 - Troubleshooting (`TROUBLESHOOTING.md`) documents how to recover when the first run fails.

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.

package/docs/examples/next.md.template

@@ -0,0 +1,27 @@
+# Next Example
+
+Use `next` to ask Quiver what slice is ready right now. The default output gives you one slice and the exact `start-slice` command to copy.
+
+## Input
+
+```bash
+npx create-quiver next
+npx create-quiver next --all-ready
+npx create-quiver next --auto-start
+```
+
+## Representative Output
+
+```text
+Next ready slice
+Slice: spec-a/slice-01-alpha
+Title: Alpha
+Status: draft
+Start: npx create-quiver start-slice "specs/spec-a/slices/slice-01-alpha/slice.json"
+```
+
+## Notes
+
+- `--all-ready` lists every slice in the first unblocked level.
+- `--auto-start` requires a TTY confirmation before it calls `start-slice`.
+- Use `--json` when another tool needs the next slice payload.

package/docs/examples/plan.md.template

@@ -0,0 +1,28 @@
+# Plan Example
+
+Use `plan` to inspect the pending slice order before starting implementation work.
+
+## Input
+
+```bash
+npx create-quiver plan
+```
+
+## Representative Output
+
+```text
+Quiver plan
+Total hours: 10
+Critical path: spec-a/slice-01-alpha -> spec-a/slice-02-beta -> spec-b/slice-01-delta
+
+[N]  TICKET   SPEC/SLICE            TITLE                 HOURS  STATUS
+---  -------  --------------------  --------------------  -----  ------
+[1]  QUIVER-1 spec-a/slice-01-alpha Alpha                 2      draft
+[2]  QUIVER-1 spec-a/slice-02-beta  Beta                  5      draft
+[3]  QUIVER-1 spec-b/slice-01-delta Delta                 3      draft
+```
+
+## Notes
+
+- The exact order depends on the repo's current pending graph.
+- Use `--json` when another tool needs the plan, critical path, or total hours.