create-quiver 0.4.0

package/docs/INDEX.md.template

@@ -0,0 +1,41 @@
+# {{PROJECT_NAME}} Documentation Index
+
+**Last updated:** {{FECHA}}
+
+## Start Here
+
+- **Context** - `./CONTEXTO.md`
+- **Workflow** - `./WORKFLOW.md`
+- **Support Matrix** - `./SUPPORT_MATRIX.md`
+- **Troubleshooting** - `./TROUBLESHOOTING.md`
+- **Multi-agent workflow** - `./MULTI_AGENT_WORKFLOW.md`
+
+## AI Configuration
+
+- **Principles** - `./ai/PRINCIPLES.md`
+- **Rules** - `./ai/RULES.yaml`
+- **Lessons** - `./ai/LESSONS.md`
+
+## Optional Docs
+
+- **Status** - `./STATUS.md`
+- **Specs** - `../specs/{{PROJECT_SLUG}}/`
+- **Tools** - `./tools/`
+- **Archive** - `./archive/`
+
+## Directory Layout
+
+```text
+docs/
+├── INDEX.md
+├── CONTEXTO.md
+├── STATUS.md
+├── WORKFLOW.md
+├── SUPPORT_MATRIX.md
+├── TROUBLESHOOTING.md
+├── MULTI_AGENT_WORKFLOW.md
+├── ai/
+├── api/
+├── tools/
+└── archive/
+```

package/docs/MOCK_DATA_GUIDE.md.template

@@ -0,0 +1,31 @@
+# Mock Data Guide
+
+**Purpose:** Define a simple mock-data approach for projects that do not have a real backend yet.
+
+## What This Covers
+
+- Mock entities
+- Stub API responses
+- Example hooks and components
+
+## Recommended Structure
+
+```text
+types/
+data/mocks/
+lib/api/
+hooks/
+app/api/
+components/
+docs/api/
+```
+
+## When to Use Mocks
+
+- The backend is not ready
+- You need UI progress without waiting for APIs
+- You need deterministic test data
+
+## Notes
+
+Keep mock data realistic and small. Do not duplicate production-only logic here.

package/docs/MULTI_AGENT_WORKFLOW.md.template

@@ -0,0 +1,31 @@
+# Multi-Agent Workflow
+
+**Date:** {{FECHA}}
+
+Use multiple agents only when the work can be split by independent ownership and merged without conflict.
+
+## When to Use
+
+- Large file exploration
+- Independent documentation updates
+- Separate feature slices with disjoint write sets
+
+## When Not to Use
+
+- One small task
+- Shared central files
+- A task where the next step depends on one immediate result
+
+## Ownership Rule
+
+Each worker must own its files or output set. If two workers need the same file, the task is not ready for parallel execution.
+
+## Delivery Rule
+
+A valid worker delivery must include:
+
+- concrete changes or findings
+- files touched
+- validation performed
+- evidence
+- open risks

package/docs/STATUS.md.template

@@ -0,0 +1,26 @@
+# {{PROJECT_NAME}} Status
+
+**Last updated:** {{FECHA}}
+**Next update:** {{FECHA_PROXIMA}}
+
+## Overall Status
+
+- Progress: {{X}}% complete
+- Current phase: {{FASE}}
+- Next milestone: [Description]
+
+## Slice Summary
+
+| Slice | Title | Status | Progress | Spec |
+|-------|-------|--------|----------|------|
+| 01 | [Name] | Done | 100% | [link](../specs/{{PROJECT_SLUG}}/slices/slice-01/slice.json) |
+
+## Blockers
+
+| Blocker | Impact | Mitigation |
+|---------|--------|------------|
+| - | - | - |
+
+## Notes
+
+- Update this file after each completed slice.

package/docs/SUPPORT_MATRIX.md.template

@@ -0,0 +1,31 @@
+# Support Matrix
+
+**Project:** {{PROJECT_NAME}}
+**Last updated:** {{FECHA}}
+
+Quiver is intentionally opinionated about the first-run environment. If your setup falls outside this matrix, the bootstrap scripts may stop early by design.
+
+## Supported Environments
+
+| 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. |
+| 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. |
+
+## Remote Modes
+
+| Mode | Supported | Notes |
+|------|-----------|-------|
+| Local base branch only | Yes | The bootstrap should still work when `origin` is unavailable. |
+| Remote base branch available | Yes | `origin/develop` or `origin/main` can be used when present. |
+| No base branch and no remote | No | Create or fetch a base branch before starting a slice. |
+
+## What This Means
+
+- You can bootstrap a slice on macOS or Linux without changing the scripts.
+- 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

@@ -0,0 +1,42 @@
+# Testing Guide for AI
+
+**Date:** [YYYY-MM-DD]
+**Purpose:** Define the testing process AI should follow for each slice.
+
+## Testing Flow
+
+1. Read the slice spec.
+2. Implement the change.
+3. Run validation commands.
+4. Capture evidence.
+5. If a bug is found, document it and create a fix slice if needed.
+
+## Before Implementation
+
+- Review `acceptance`
+- Review `tests`
+- Review `files`
+
+## During Implementation
+
+- Keep changes within scope
+- Check syntax and linting early
+- Capture intermediate evidence when useful
+
+## After Implementation
+
+- Run the slice validation gate
+- Run the PR validation gate
+- Store evidence in `test-results/`
+
+## Evidence
+
+- Logs
+- Screenshots
+- Diff output
+
+## If Something Fails
+
+1. Fix the issue.
+2. Re-run validation.
+3. Update the evidence.

package/docs/TROUBLESHOOTING.md.template

@@ -0,0 +1,70 @@
+# Troubleshooting
+
+**Project:** {{PROJECT_NAME}}
+**Last updated:** {{FECHA}}
+
+Use this guide when a first-run bootstrap or gate check fails. The recovery paths below follow the smoke-tested flows in this repository.
+
+## Path Normalization Failure
+
+### Symptom
+
+- `start-slice.sh` rejects a slice that exists
+- The repo path and the slice path differ only by a symlinked or canonicalized prefix
+
+### Recovery
+
+1. Re-run the command from the physical repo path.
+2. Pass the slice path from the same filesystem view that the repo uses.
+3. Avoid mixing `/tmp/...` and `/private/tmp/...` or other alias paths.
+
+## Missing Base Branch
+
+### Symptom
+
+- `start-slice.sh` reports that it cannot find `develop` or `main`
+- The repo has no local base branch and no usable remote ref
+
+### Recovery
+
+1. Create or fetch the base branch locally.
+2. Re-run the slice bootstrap after `develop` or `main` is visible to git.
+3. If the remote exists but is stale, fetch it before retrying.
+
+## Remote Mode Issues
+
+### Symptom
+
+- The repository works locally but fails as soon as `origin` is removed
+- The bootstrap assumes a remote exists even though the workflow should support local-only setup
+
+### Recovery
+
+1. Keep a local `develop` or `main` branch available.
+2. Re-add the remote only if the workflow genuinely needs it.
+3. Prefer the local base branch path when validating first-run behavior.
+
+## Generated File Conflicts
+
+### Symptom
+
+- `init-docs.sh` or a slice bootstrap stops because a file already exists
+- The generated project has a partially initialized docs tree
+
+### Recovery
+
+1. Check whether the target file is meant to be preserved.
+2. Remove the conflicting generated file only if it is safe to regenerate.
+3. Re-run the bootstrap after the docs tree is consistent again.
+
+## Clean Worktree Failures
+
+### Symptom
+
+- `check-pr-readiness.sh` reports that the worktree is dirty
+
+### Recovery
+
+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.

package/docs/UI_STANDARDS.md.template

@@ -0,0 +1,31 @@
+# UI Standards
+
+**Version:** 1.0
+**Last updated:** {{FECHA}}
+
+## Principles
+
+1. Consistency
+2. Accessibility
+3. Responsive layout
+4. Performance
+
+## Baseline Tokens
+
+Use CSS variables or design tokens for:
+
+- colors
+- spacing
+- typography
+- radii
+- shadows
+
+## Interaction Rules
+
+- Use clear focus states
+- Use visible disabled states
+- Keep hover and press feedback consistent
+
+## Notes
+
+If the project has no UI, delete this file from the generated project.

package/docs/WORKFLOW.md.template

@@ -0,0 +1,56 @@
+# Workflow
+
+**Date:** {{FECHA}}
+
+This document is the canonical implementation workflow for the project.
+
+## Core Rules
+
+- Do not implement without a slice.
+- One slice maps to one commit.
+- One spec maps to one PR.
+- Slice numbering is local to each spec. Every spec starts at `slice-01`.
+- The spec defines the plan; the slice defines the execution.
+- No slice should enter execution until it is `ready`.
+- The documentation PR establishes the workflow files before the first slice executes.
+- 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.
+
+## Planning
+
+1. Triage the request.
+2. Decide whether to create a new spec or reuse an existing one.
+3. Split the work into slices.
+4. Mark each slice `ready` before execution.
+5. Open and merge the documentation PR before running the first slice bootstrap.
+6. Read the support matrix and troubleshooting guide before the first slice if the environment is new or uncertain.
+
+## Execution
+
+1. Bootstrap the slice with `start-slice.sh`.
+   - 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.
+2. Implement only what the slice declares.
+3. Make one commit for that slice.
+4. Validate with `check-slice-readiness.sh`.
+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.
+
+## Support Contract
+
+- Support Matrix (`SUPPORT_MATRIX.md`) documents what is supported.
+- Troubleshooting (`TROUBLESHOOTING.md`) documents how to recover when the first run fails.
+- Keep both files linked from the root README and this workflow doc.
+
+## Multi-Agent Rule
+
+Use multiple agents only when the write sets do not overlap and the coordination cost is lower than the gain.
+
+## References
+
+- `GITFLOW_PR_GUIDE.md`
+- `SUPPORT_MATRIX.md`
+- `TROUBLESHOOTING.md`
+- `MULTI_AGENT_WORKFLOW.md`
+- `TESTING_GUIDE_FOR_AI.md`

package/docs/ai/LESSONS.md.template

@@ -0,0 +1,24 @@
+# Lessons Learned
+
+**Last updated:** {{FECHA}}
+
+## [Lesson Title]
+
+### Context
+
+[What happened]
+
+### What Worked
+
+- [Item 1]
+- [Item 2]
+
+### What Did Not Work
+
+- [Item 1]
+- [Item 2]
+
+### Next Time
+
+- [Rule 1]
+- [Rule 2]

package/docs/ai/PRINCIPLES.md

@@ -0,0 +1,25 @@
+# AI Principles
+
+**Last updated:** 2026-03-13
+
+## 1. Privacy First
+
+- Never log sensitive data.
+- Never expose secrets in logs or errors.
+- Always use environment variables for secrets.
+
+## 2. Simple Is Better
+
+- Choose the simplest solution that works.
+- Avoid speculative abstractions.
+- Prefer MVP-first implementation.
+
+## 3. Test Before Commit
+
+- Functional changes need tests or manual verification.
+- Do not commit a change that you cannot validate.
+
+## 4. Document as You Go
+
+- Update docs when behavior or scope changes.
+- Keep specs and operational docs aligned with the code.

package/docs/ai/RULES.yaml

@@ -0,0 +1,33 @@
+version: 1.0.0
+last_updated: 2026-03-13
+next_review: 2026-03-20
+
+planning:
+  auto_trigger_if:
+    - files_to_change > 5
+    - includes_architecture_decision: true
+    - includes_db_migration: true
+    - estimated_complexity > 7/10
+    - first_time_doing_this_task: true
+  skip_if:
+    - files_to_change <= 2
+    - similar_task_done_before: true
+
+review:
+  auto_check:
+    tests_pass: true
+    lint_pass: true
+    type_check_pass: true
+    no_console_log: true
+    no_debugger: true
+  review_criteria:
+    - "Are there tests for functional changes?"
+    - "Is the code readable without extra explanation?"
+    - "Does the implementation follow existing patterns?"
+    - "Are there hidden side effects?"
+
+testing:
+  evidence:
+    screenshots: "test-results/screenshots/"
+    logs: "test-results/logs/"
+    reports: "test-results/SLICE-XX-EVIDENCE-REPORT.md"

package/i18n/es/README.md

@@ -0,0 +1,15 @@
+# Quiver Plantilla de Documentación
+
+Quiver es una plantilla de documentación primero para proyectos que usan specs, slices y ejecución asistida por IA.
+
+## Inicio Rápido
+
+1. Copiá esta carpeta como `docs-template/` dentro del proyecto destino.
+2. Ejecutá:
+
+```bash
+./docs-template/scripts/init-docs.sh "Nombre del Proyecto"
+```
+
+3. Editá los docs generados en `docs/` y el spec del proyecto en `specs/[project-name]/`.
+

package/i18n/es/README_FOR_AI.md

@@ -0,0 +1,6 @@
+# Guía para Agentes de IA
+
+- No personalices `docs-template/` para un proyecto específico.
+- Usá siempre `init-docs.sh`.
+- Considerá `docs-template/` como genérico y `docs/` como salida específica.
+

package/i18n/es/TEMPLATE.md

@@ -0,0 +1,18 @@
+# Guía de Personalización
+
+Usá esta guía para adaptar la plantilla a un proyecto concreto.
+
+## Setup
+
+1. Ejecutá:
+
+```bash
+./scripts/init-docs.sh "Nombre del Proyecto"
+```
+
+2. Editá:
+
+- `docs/CONTEXTO.md`
+- `docs/STATUS.md` si hace falta
+- `specs/[project-name]/SPEC.md`
+

package/i18n/es/docs/CONTEXTO.md.template

@@ -0,0 +1,9 @@
+# Contexto de {{PROJECT_NAME}}
+
+**Fecha:** {{FECHA}}
+**Estado:** {{ESTADO}}
+
+## ¿Qué es {{PROJECT_NAME}}?
+
+[Descripción breve del proyecto.]
+

package/i18n/es/docs/DOCUMENTATION_GUIDE.md.template

@@ -0,0 +1,4 @@
+# Guía de Documentación
+
+Orden recomendado: índice, contexto, estado, workflow y spec.
+

package/i18n/es/docs/GITFLOW_PR_GUIDE.md.template

@@ -0,0 +1,4 @@
+# Guía de Git y PR
+
+Usá un branch, un worktree y un PR por slice.
+

package/i18n/es/docs/INDEX.md.template

@@ -0,0 +1,10 @@
+# Índice de Documentación de {{PROJECT_NAME}}
+
+**Última actualización:** {{FECHA}}
+
+## Empezar acá
+
+- Contexto
+- Workflow
+- Workflow multi-agente
+

package/i18n/es/docs/MOCK_DATA_GUIDE.md.template

@@ -0,0 +1,4 @@
+# Guía de Datos Mock
+
+Definí aquí los datos falsos que usa el proyecto cuando no hay backend real.
+

package/i18n/es/docs/MULTI_AGENT_WORKFLOW.md.template

@@ -0,0 +1,4 @@
+# Workflow Multi-Agente
+
+Usá múltiples agentes sólo cuando el trabajo pueda dividirse sin superposición.
+

package/i18n/es/docs/STATUS.md.template

@@ -0,0 +1,9 @@
+# Estado de {{PROJECT_NAME}}
+
+**Última actualización:** {{FECHA}}
+
+## Estado general
+
+- Progreso: {{X}}%
+- Fase actual: {{FASE}}
+

package/i18n/es/docs/TESTING_GUIDE_FOR_AI.md.template

@@ -0,0 +1,7 @@
+# Guía de Testing para IA
+
+1. Leer el slice.
+2. Implementar.
+3. Validar.
+4. Registrar evidencia.
+

package/i18n/es/docs/UI_STANDARDS.md.template

@@ -0,0 +1,4 @@
+# Estándares de UI
+
+Usá esta guía si el proyecto tiene interfaz.
+

package/i18n/es/docs/WORKFLOW.md.template

@@ -0,0 +1,6 @@
+# Workflow
+
+**Fecha:** {{FECHA}}
+
+Este documento define el flujo canónico de implementación.
+

package/i18n/es/docs/ai/LESSONS.md.template

@@ -0,0 +1,3 @@
+# Lecciones Aprendidas
+
+Plantilla vacía para registrar aprendizajes del proyecto.

package/i18n/es/docs/ai/PRINCIPLES.md

@@ -0,0 +1,7 @@
+# Principios de IA
+
+- Privacidad primero
+- Simple es mejor
+- Probar antes de commitear
+- Documentar mientras se hace
+

package/i18n/es/docs/ai/RULES.yaml

@@ -0,0 +1,7 @@
+version: 1.0.0
+last_updated: 2026-03-13
+
+planning:
+  auto_trigger_if:
+    - files_to_change > 5
+

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "create-quiver",
+  "version": "0.4.0",
+  "private": false,
+  "description": "Quiver CLI for scaffolding projects from the packaged template",
+  "license": "MIT",
+  "bin": {
+    "create-quiver": "./bin/create-quiver.js"
+  },
+  "scripts": {
+    "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",
+    "package:quiver": "bash scripts/package-quiver.sh",
+    "smoke:create-quiver": "bash scripts/ci/smoke-create-quiver.sh",
+    "release:quiver": "bash scripts/release-quiver.sh"
+  }
+}

package/package.template.json

@@ -0,0 +1,10 @@
+{
+  "name": "quiver-docs-template",
+  "private": true,
+  "scripts": {
+    "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"
+  }
+}