create-quiver 0.6.0 → 0.7.0

package/.github/workflows/ci.yml

@@ -25,13 +25,14 @@ jobs:
           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'))"
 
-  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/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- Cross-platform CI matrix covering macOS, Linux, and Windows for the Node-native Quiver runtime
+- Node-native generated project npm scripts and additive migration support for existing projects
+
 ## [0.4.0] - 2026-04-21
 
 ### Added

package/README.md

@@ -34,18 +34,36 @@ 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 doctor
 ```
 
-If you are working in the current directory, use `--dir .`.
+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.
+
+### 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: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
+```
+
+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.
 
 ### 3. Upgrade Existing Projects
 
@@ -53,18 +71,18 @@ 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 doctor
 ```
 
 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 doctor
 ```
 
 ### 4. Ask The AI To Prepare Context
@@ -85,7 +103,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 +113,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:

package/README_FOR_AI.md

@@ -7,11 +7,28 @@ 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, 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.
 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`.
+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.
+- **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 +36,13 @@ 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.
 - 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`.
 
 ## Initialization Flow
 
@@ -76,19 +96,19 @@ 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>`
+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 `tools/scripts/start-slice.sh [--allow-draft] <slice.json>`
+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
 
-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.
+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,81 @@
 - 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 (unreleased)
+
+- 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)
+
+- **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 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
+
+## 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.
+
+### v15 — 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

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

@@ -19,10 +19,22 @@ You are the onboarding agent for this project. Your job is to analyze the genera
 ## 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.
 - 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/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,8 +4,10 @@
 
 ## 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`
 - **Support Matrix** - `./SUPPORT_MATRIX.md`
@@ -14,6 +16,9 @@
 
 ## 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,6 +36,10 @@
 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

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`