create-quiver 0.5.0 → 0.7.0

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,9 +9,10 @@ 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. |
@@ -26,6 +27,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

@@ -17,6 +17,15 @@ This document is the canonical implementation workflow for the project.
 - 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.
 
+## 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.
+- **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
 
 1. Triage the request.
@@ -25,22 +34,27 @@ This document is the canonical implementation workflow for the project.
 4. Mark each slice `ready` before execution.
 5. Open and merge the documentation PR before running the first slice bootstrap.
 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 was analyzed, read `AI_ONBOARDING_PROMPT.md` before making documentation updates.
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",
@@ -12,8 +12,10 @@
     "check:pr": "bash tools/scripts/check-pr-readiness.sh",
     "start:slice": "bash tools/scripts/start-slice.sh",
     "cleanup:slice": "bash tools/scripts/cleanup-slice.sh",
+    "migrate": "bash tools/scripts/migrate-project.sh",
     "package:quiver": "bash scripts/package-quiver.sh",
     "smoke:create-quiver": "bash scripts/ci/smoke-create-quiver.sh",
+    "smoke:tiered-pack": "bash scripts/ci/smoke-tiered-pack.sh",
     "release:quiver": "bash scripts/release-quiver.sh"
   }
 }

package/package.template.json

@@ -2,9 +2,21 @@
   "name": "quiver-docs-template",
   "private": true,
   "scripts": {
+    "quiver:migrate": "npx create-quiver migrate",
+    "quiver:analyze": "npx create-quiver analyze",
+    "quiver:doctor": "npx create-quiver doctor",
+    "quiver:start-slice": "npx create-quiver start-slice",
+    "quiver:check-slice": "npx create-quiver check-slice",
+    "quiver:check-pr": "npx create-quiver check-pr",
+    "quiver:cleanup-slice": "npx create-quiver cleanup-slice",
+    "quiver:check-scope": "npx create-quiver check-scope",
+    "quiver:refresh-active-slices": "npx create-quiver refresh-active-slices",
     "check:slice": "bash tools/scripts/check-slice-readiness.sh",
     "check:pr": "bash tools/scripts/check-pr-readiness.sh",
     "start:slice": "bash tools/scripts/start-slice.sh",
-    "cleanup:slice": "bash tools/scripts/cleanup-slice.sh"
+    "cleanup:slice": "bash tools/scripts/cleanup-slice.sh",
+    "check:scope": "bash tools/scripts/check-scope.sh",
+    "refresh:active-slices": "bash tools/scripts/refresh-active-slices.sh",
+    "migrate": "bash tools/scripts/migrate-project.sh"
   }
 }

package/scripts/cleanup-slice.sh

@@ -2,176 +2,6 @@
 
 set -euo pipefail
 
-usage() {
-  cat <<'EOF'
-Uso:
-  bash tools/scripts/cleanup-slice.sh <ruta-al-slice.json> [--close-baseline] [--discard] [--force] [--dry-run]
-
-Politica:
-- slice-00: queda congelado por default; no se elimina salvo --close-baseline
-- slice-01+: se elimina despues de merge/rechazo/reemplazo segun la politica del repo
-
-Opciones:
-  --close-baseline  Permite cerrar y eliminar un slice-00 congelado
-  --discard         Permite cerrar un slice no mergeado (descartado/reemplazado)
-  --force           Fuerza git worktree remove --force y git branch -D
-  --dry-run         Solo informa que haria, no ejecuta cambios
-EOF
-}
-
-fail() {
-  echo "FAIL: $1" >&2
-  exit 1
-}
-
-pass() {
-  echo "PASS: $1"
-}
-
-close_baseline="false"
-discard="false"
-force_delete="false"
-dry_run="false"
-slice_input=""
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    -h|--help)
-      usage
-      exit 0
-      ;;
-    --close-baseline)
-      close_baseline="true"
-      ;;
-    --discard)
-      discard="true"
-      ;;
-    --force)
-      force_delete="true"
-      ;;
-    --dry-run)
-      dry_run="true"
-      ;;
-    -*)
-      fail "Opcion desconocida: $1"
-      ;;
-    *)
-      if [[ -n "$slice_input" ]]; then
-        fail "Solo se acepta un slice por ejecucion."
-      fi
-      slice_input="$1"
-      ;;
-  esac
-  shift
-done
-
-[[ -n "$slice_input" ]] || {
-  usage
-  exit 1
-}
-
-command -v git >/dev/null 2>&1 || fail "git no esta disponible en PATH."
-command -v node >/dev/null 2>&1 || fail "node no esta disponible en PATH."
-
 repo_root="$(git rev-parse --show-toplevel)"
-
-[[ -f "$slice_input" ]] || fail "No existe el slice '$slice_input'."
-
-slice_abs="$(cd "$(dirname "$slice_input")" && pwd)/$(basename "$slice_input")"
-
-slice_meta=()
-while IFS= read -r line; do
-  slice_meta+=("$line")
-done < <(node - "$slice_abs" "$repo_root" <<'NODE'
-const fs = require('fs');
-const path = require('path');
-
-const [slicePath, repoRoot] = process.argv.slice(2);
-const json = JSON.parse(fs.readFileSync(slicePath, 'utf8'));
-
-const branchName = String(json.git?.branch_name || '').trim();
-const sliceId = String(json.slice_id || '').trim();
-const isBaseline = sliceId.startsWith('slice-00');
-const repoName = path.basename(repoRoot);
-const repoParent = path.dirname(repoRoot);
-const worktreesRoot = process.env.SLICE_WORKTREES_DIR || path.join(repoParent, '.worktrees', repoName);
-const safeBranchName = branchName.replace(/[^A-Za-z0-9._-]/g, '-');
-const worktreePath = path.join(worktreesRoot, safeBranchName);
-
-console.log(branchName);
-console.log(sliceId);
-console.log(isBaseline ? 'true' : 'false');
-console.log(worktreePath);
-NODE
-)
-
-[[ ${#slice_meta[@]} -eq 4 ]] || fail "No se pudo leer la metadata de cleanup del slice."
-
-branch_name="${slice_meta[0]}"
-slice_id="${slice_meta[1]}"
-is_baseline="${slice_meta[2]}"
-worktree_path="${slice_meta[3]}"
-
-[[ -n "$branch_name" ]] || fail "Falta git.branch_name en el slice."
-
-if [[ "$is_baseline" == "true" && "$close_baseline" != "true" ]]; then
-  echo "INFO: '$slice_id' es baseline. El worktree queda congelado por default."
-  echo "INFO: Usa --close-baseline solo cuando la primera ola del spec ya este estable o mergeada."
-  exit 0
-fi
-
-current_branch="$(git branch --show-current)"
-
-if [[ "$discard" != "true" ]]; then
-  [[ "$current_branch" == "develop" ]] || fail "El cleanup normal debe correrse desde develop. Rama actual: $current_branch"
-  [[ -z "$(git status --porcelain)" ]] || fail "El checkout actual no esta limpio. Limpialo antes del cleanup."
-
-  git fetch origin develop >/dev/null 2>&1 || true
-
-  local_develop_sha="$(git rev-parse HEAD)"
-  remote_develop_sha="$(git rev-parse origin/develop)"
-  [[ "$local_develop_sha" == "$remote_develop_sha" ]] || fail "develop local no esta actualizado. Ejecuta git pull --ff-only antes del cleanup."
-
-  if git show-ref --verify --quiet "refs/heads/$branch_name"; then
-    git merge-base --is-ancestor "$branch_name" "origin/develop" || fail "La rama '$branch_name' no esta mergeada en origin/develop. Usa --discard si el slice se descarta."
-  fi
-fi
-
-worktree_exists="false"
-branch_exists="false"
-
-[[ -d "$worktree_path" ]] && worktree_exists="true"
-git show-ref --verify --quiet "refs/heads/$branch_name" && branch_exists="true"
-
-[[ "$worktree_exists" == "true" || "$branch_exists" == "true" ]] || fail "No existe worktree ni rama local para '$slice_id'."
-
-remove_worktree_cmd=(git worktree remove "$worktree_path")
-remove_branch_cmd=(git branch -d "$branch_name")
-
-if [[ "$force_delete" == "true" || "$discard" == "true" ]]; then
-  remove_worktree_cmd=(git worktree remove --force "$worktree_path")
-  remove_branch_cmd=(git branch -D "$branch_name")
-fi
-
-if [[ "$dry_run" == "true" ]]; then
-  echo "DRY RUN: slice=$slice_id branch=$branch_name"
-  [[ "$worktree_exists" == "true" ]] && echo "DRY RUN: ${remove_worktree_cmd[*]}"
-  [[ "$branch_exists" == "true" ]] && echo "DRY RUN: ${remove_branch_cmd[*]}"
-  exit 0
-fi
-
-if [[ "$worktree_exists" == "true" ]]; then
-  "${remove_worktree_cmd[@]}"
-  pass "Worktree eliminado: $worktree_path"
-fi
-
-if [[ "$branch_exists" == "true" ]]; then
-  "${remove_branch_cmd[@]}"
-  pass "Rama local eliminada: $branch_name"
-fi
-
-if [[ -x "$repo_root/tools/scripts/refresh-active-slices.sh" ]]; then
-  "$repo_root/tools/scripts/refresh-active-slices.sh" >/dev/null 2>&1 || true
-fi
-
-pass "Cleanup finalizado para '$slice_id'."
+cd "$repo_root"
+exec npx create-quiver cleanup-slice "$@"