create-quiver 0.4.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,15 @@
+---
+name: Bug report
+about: Report a problem in the template or the workflow
+title: "[Bug]"
+labels: bug
+---
+
+## What happened
+
+## Expected behavior
+
+## Steps to reproduce
+
+## Evidence
+

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,15 @@
+---
+name: Feature request
+about: Propose a new capability or improvement
+title: "[Feature]"
+labels: enhancement
+---
+
+## Problem statement
+
+## Proposed solution
+
+## Alternatives considered
+
+## Additional context
+

package/.github/pull_request_template.md

@@ -0,0 +1,4 @@
+# PR Template
+
+Please fill in the slice `pr.md` and keep this PR aligned with it.
+

package/.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install shellcheck
+        run: sudo apt-get update && sudo apt-get install -y shellcheck
+
+      - name: Shellcheck scripts
+        run: shellcheck scripts/*.sh
+
+      - 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'))"
+
+  smoke-init-docs:
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - macos-latest
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Run init-docs smoke
+        run: bash scripts/ci/smoke-init-docs.sh "Smoke Project"
+
+  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

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.4.0] - 2026-04-21
+
+### Added
+
+- `create-quiver` CLI installer surface
+- Post-init `doctor` validation mode
+- Release helper script and packaged-installer smoke checks
+
+## [0.1.0] - 2026-04-20
+
+### Added
+
+- MIT license
+- Portable `init-docs.sh`
+- `package.template.json`
+- English canonical documentation
+- `examples/01-basic-slice/`
+- Community health docs and CI

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,12 @@
+# Code of Conduct
+
+This project follows the Contributor Covenant v2.1.
+
+## Our Pledge
+
+We are committed to providing a welcoming, respectful, and harassment-free experience for everyone.
+
+## Enforcement
+
+Report issues to the project maintainers or through the security/contact channel used by the repository.
+

package/CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing
+
+## How to Contribute
+
+1. Open an issue describing the problem or proposal.
+2. Wait for the scope to be clarified if needed.
+3. Open a pull request that matches one slice.
+4. Link the issue and the slice in the PR body.
+
+## Expectations
+
+- Keep changes small and scoped.
+- Follow the slice workflow.
+- Include evidence when the change needs validation.
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabri Juncal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# Quiver
+
+Quiver is a CLI-first documentation workflow for projects that use specs, slices, and AI-assisted implementation.
+
+It gives a project a repeatable structure for planning work, starting focused implementation slices, validating readiness, and keeping human and AI contributors aligned.
+
+## Quick Start
+
+Create or update a project with the installer:
+
+```bash
+npx create-quiver --name "Project Name" --dir ./target-repo
+```
+
+To install into the current directory, omit `--dir`:
+
+```bash
+npx create-quiver --name "Project Name"
+```
+
+## Requirements
+
+- 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
+
+See the generated `docs/SUPPORT_MATRIX.md` for the detailed support contract.
+
+## Validate
+
+After installation, run the doctor:
+
+```bash
+npx create-quiver doctor --dir ./target-repo
+```
+
+The doctor checks the generated project contract and prints the next workflow steps.
+
+## First Slice Workflow
+
+After the scaffold is valid:
+
+1. Fill in `docs/CONTEXTO.md` and `docs/STATUS.md`.
+2. Define the project spec in `specs/<project-slug>/SPEC.md`.
+3. Create the first slice from `specs/<project-slug>/slices/slice-template/slice.json`.
+4. Start work with `tools/scripts/start-slice.sh <slice.json>`.
+5. Make one commit per slice.
+6. Open one PR per spec.
+
+Slice numbering is local to each spec: every new spec starts at `slice-01`.
+
+## What Gets Generated
+
+Quiver generates a project-local workflow under:
+
+- `docs/` for project context, workflow, support, troubleshooting, and AI guidance
+- `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
+- `package.json` scripts for the workflow commands
+
+For the detailed support contract, read `docs/SUPPORT_MATRIX.md` in the generated project. For recovery paths, read `docs/TROUBLESHOOTING.md`.
+
+## Manual Template Use
+
+Use the manual flow only when developing Quiver locally or testing a template checkout. From a target project where this repository was copied as `docs-template/`, run:
+
+```bash
+./docs-template/scripts/init-docs.sh "Project Name"
+```
+
+The CLI path is the supported adoption path for users.
+
+## For AI Agents
+
+Read `README_FOR_AI.md` before working in this repository or in a generated project. It explains the generic template boundary, the generated project boundary, and the slice workflow rules.
+
+## For Maintainers
+
+Release preflight:
+
+```bash
+npm whoami
+npm view create-quiver version
+npm run package:quiver
+npm run smoke:create-quiver
+npm run release:quiver
+```
+
+Current-version publish:
+
+```bash
+bash scripts/release-quiver.sh --publish-current
+```
+
+Versioned publish:
+
+```bash
+bash scripts/release-quiver.sh patch --publish
+```
+
+The release helper stays explicit on purpose: `--publish-current` publishes the current version, and `--publish` follows a normal version bump flow.
+
+If `npm whoami` or `npm view create-quiver version` fails, fix npm auth or registry reachability before publishing.
+
+For a first release, prefer `--publish-current` so the published package stays at `0.4.0`.
+
+## References
+
+- [AI guide](./README_FOR_AI.md)
+- [Support matrix template](./docs/SUPPORT_MATRIX.md.template)
+- [Troubleshooting template](./docs/TROUBLESHOOTING.md.template)
+- [Changelog](./CHANGELOG.md)
+- [Roadmap](./ROADMAP.md)
+
+## License
+
+MIT

package/README_FOR_AI.md

@@ -0,0 +1,90 @@
+# AI Guide for Quiver Docs Template
+
+Use this guide when initializing a new project from the template or when explaining the workflow to another agent.
+
+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`.
+The post-init contract is validated with `npx create-quiver doctor --dir <project>`.
+Maintain release notes and package publishing with `scripts/release-quiver.sh`.
+
+## Core Rules
+
+- Never customize `docs-template/` for a specific project.
+- 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 support contract lives in `docs/SUPPORT_MATRIX.md` and `docs/TROUBLESHOOTING.md`.
+
+## Initialization Flow
+
+1. Copy the template folder into the target project as `docs-template/`.
+2. Run:
+
+```bash
+./docs-template/scripts/init-docs.sh "Project Name"
+```
+
+3. Tell the user to edit:
+  - `docs/CONTEXTO.md`
+  - `docs/STATUS.md`
+  - `docs/SUPPORT_MATRIX.md`
+  - `docs/TROUBLESHOOTING.md`
+  - `specs/{{PROJECT_SLUG}}/SPEC.md`
+
+## What the Script Creates
+
+- `docs/`
+- `docs/ai/`
+- `specs/{{PROJECT_SLUG}}/`
+- `tools/scripts/`
+- `docs/SEARCH.md`
+- a merged or copied `package.json` with the required npm scripts
+- the default OSS baseline when those files are missing:
+- `LICENSE`
+- `CONTRIBUTING.md`
+- `CODE_OF_CONDUCT.md`
+- `SECURITY.md`
+- `CHANGELOG.md`
+- `ROADMAP.md`
+- `docs/SUPPORT_MATRIX.md`
+- `docs/TROUBLESHOOTING.md`
+- `.github/pull_request_template.md`
+- `.github/ISSUE_TEMPLATE/bug_report.md`
+- `.github/ISSUE_TEMPLATE/feature_request.md`
+- `.github/workflows/ci.yml`
+
+`init-docs.sh` preserves any existing target files and reports skipped copies instead of overwriting them.
+
+## Required Follow-Up
+
+After initialization, the user should:
+
+1. Fill in `docs/CONTEXTO.md`
+2. Fill in `docs/STATUS.md`
+3. Open and merge the documentation PR that establishes the workflow files
+4. Create the first slice in `specs/{{PROJECT_SLUG}}/slices/[slice-id]/`
+5. Add `ticket` and `git.*`
+6. Run `tools/scripts/start-slice.sh [--allow-draft] <slice.json>`
+7. Make one commit per slice
+8. Open one PR per spec
+9. 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.
+
+## Optional Files
+
+- `docs/MOCK_DATA_GUIDE.md` if the project uses mock data
+- `docs/UI_STANDARDS.md` if the project has UI
+- `docs/GITFLOW_PR_GUIDE.md` if the team wants a stricter branch workflow
+- `docs/SUPPORT_MATRIX.md` and `docs/TROUBLESHOOTING.md` for first-run support
+- `docs/ai/LESSONS.md` after each slice
+
+## Good Defaults
+
+- Simple project: `INDEX`, `CONTEXTO`, `WORKFLOW`, and the AI files
+- Medium project: add `STATUS.md`
+- Complex project: use the full documentation set
+
+## Reminder
+
+If a file does not exist in the generated project, do not invent it. Either create it from the template or tell the user what is missing.

package/ROADMAP.md

@@ -0,0 +1,20 @@
+# Roadmap
+
+## v0.1
+
+- Publish the OSS foundation
+- Make the quick start executable
+- Ship one complete example
+
+## v0.2
+
+- Add `npx create-quiver`
+- Add a docs site
+- Add JSON Schema for slices
+
+## v0.3
+
+- Expand automation and testing
+- Add richer templates and examples
+- Improve release workflows
+

package/SECURITY.md

@@ -0,0 +1,12 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are applied to the current active version of the repository and the latest public release.
+
+## Reporting a Vulnerability
+
+- Do not open a public issue for a security bug.
+- Report the issue privately to the maintainers.
+- Include reproduction steps and impact if possible.
+

package/TEMPLATE.md

@@ -0,0 +1,108 @@
+# Template Customization Guide
+
+Use this guide to adapt the template to a specific project.
+
+Slice numbering is local to each spec. Do not continue numbers across specs.
+
+## Setup
+
+1. Run:
+
+```bash
+./scripts/init-docs.sh "Project Name"
+```
+
+2. Edit the generated core files:
+
+- `docs/CONTEXTO.md`
+- `docs/STATUS.md` if the project needs status tracking
+- `docs/SUPPORT_MATRIX.md`
+- `docs/TROUBLESHOOTING.md`
+- `specs/{{PROJECT_SLUG}}/SPEC.md`
+
+## Generated by Default
+
+`init-docs.sh` copies these baseline OSS files when they are missing:
+
+- `LICENSE`
+- `CONTRIBUTING.md`
+- `CODE_OF_CONDUCT.md`
+- `SECURITY.md`
+- `CHANGELOG.md`
+- `ROADMAP.md`
+- `.github/pull_request_template.md`
+- `.github/ISSUE_TEMPLATE/bug_report.md`
+- `.github/ISSUE_TEMPLATE/feature_request.md`
+- `.github/workflows/ci.yml`
+
+## What to Update
+
+### `docs/CONTEXTO.md`
+
+- what the project is
+- who it is for
+- what problem it solves
+- the tech stack
+
+### `docs/STATUS.md`
+
+- progress
+- next milestone
+- slice status
+
+### `docs/WORKFLOW.md`
+
+- project-specific commands
+- stack assumptions
+- directory structure
+
+### `docs/SUPPORT_MATRIX.md`
+
+- supported operating systems
+- git expectations
+- node expectations
+- remote mode support
+
+### `docs/TROUBLESHOOTING.md`
+
+- path normalization recovery
+- missing base branch recovery
+- remote mode recovery
+- generated-file conflict recovery
+
+### `specs/{{PROJECT_SLUG}}/SPEC.md`
+
+- project objective
+- scope
+- timeline
+- dependencies
+
+## AI Files
+
+- Keep `docs/ai/PRINCIPLES.md` as the base policy and add only project-specific notes when needed.
+- Update `docs/ai/RULES.yaml` when the workflow changes.
+- Keep `docs/ai/LESSONS.md` empty until the first lesson is worth recording.
+
+## Optional Files
+
+Add these only when they apply:
+
+- `docs/api/` for backend/API docs
+- `docs/tools/` for tool-specific docs
+- `docs/UI_STANDARDS.md` for UI-heavy projects
+- `docs/MOCK_DATA_GUIDE.md` for mock-driven work
+- `docs/SUPPORT_MATRIX.md` for supported-environment documentation
+- `docs/TROUBLESHOOTING.md` for first-run recovery guidance
+
+## Common Mistakes
+
+- Overloading `CONTEXTO.md` with historical narrative
+- Letting `STATUS.md` drift out of date
+- Editing the template files directly instead of the generated project files
+
+## Time Budget
+
+- Setup: 30 minutes
+- AI configuration: 15 minutes
+- First slice: 20 minutes
+- Total: about 1 hour

package/bin/create-quiver.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { run } = require('../src/create-quiver');
+
+run(process.argv.slice(2)).catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/docs/CONTEXTO.md.template

@@ -0,0 +1,45 @@
+# {{PROJECT_NAME}} Context
+
+**Date:** {{FECHA}}
+**Status:** {{ESTADO}}
+
+## What Is {{PROJECT_NAME}}?
+
+[One or two paragraphs that explain the project.]
+
+## Value Proposition
+
+> "[Project tagline]"
+
+## Target User
+
+[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]
+
+## Security and Privacy
+
+- [Sensitive data that is never stored]
+- [Data that is stored]
+- [Important security measure]
+
+## Next Step
+
+Read `INDEX.md` to navigate the rest of the documentation.

package/docs/DOCUMENTATION_GUIDE.md.template

@@ -0,0 +1,34 @@
+# Documentation Guide
+
+**Version:** 1.0
+**Last updated:** {{FECHA}}
+
+## Reading Order
+
+1. `docs/INDEX.md`
+2. `docs/CONTEXTO.md`
+3. `docs/STATUS.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`
+
+## Update Rules
+
+- Update docs when scope changes.
+- Update `STATUS.md` after each completed slice.
+- Keep `pr.md` aligned with the slice.
+
+## Where Things Go
+
+- Project overview: `docs/CONTEXTO.md`
+- Progress: `docs/STATUS.md`
+- Implementation workflow: `docs/WORKFLOW.md`
+- Support contract: `docs/SUPPORT_MATRIX.md`
+- Recovery guidance: `docs/TROUBLESHOOTING.md`
+- Slice contract: `specs/{{PROJECT_SLUG}}/slices/[slice-id]/slice.json`
+
+## Notes
+
+Do not invent documentation files. Create them only when they are actually needed.

package/docs/GITFLOW_PR_GUIDE.md.template

@@ -0,0 +1,52 @@
+# Git and PR Guide
+
+**Version:** 2.0
+**Last updated:** {{FECHA}}
+
+## Purpose
+
+This guide explains how to open and review spec PRs without breaking the canonical workflow.
+
+## Core Rule
+
+- One slice = one commit
+- One spec = one PR
+- Slice numbers reset per spec. `slice-01` is the first slice in each spec.
+- Do not commit directly to `develop`
+- Open and merge the documentation PR before the first slice starts execution
+- Do not open the spec PR before the documentation PR is merged
+
+## Required PR Headings
+
+All spec PR notes must use:
+
+- `## Title`
+- `## Summary`
+- `## Scope`
+- `## Files`
+- `## How to Test (DETAILED - REQUIRED)`
+- `## Evidence`
+- `## Rollback`
+- `## Risks / Notes`
+
+Inside `How to Test`, use:
+
+- `### Required Environment`
+- `### Worktree Access`
+- `### Run the Project`
+- `### Use Cases`
+- `### Technical Verification`
+
+## Branch Strategy
+
+| Type | Prefix | Source | Target |
+|------|--------|--------|--------|
+| feature | `feature/` | `develop` | `develop` |
+| bugfix | `bugfix/` | `develop` | `develop` |
+| hotfix | `hotfix/` | `main` | `main` |
+
+## Anti-Patterns
+
+- Pushing directly to `develop`
+- Reusing the same branch for multiple specs
+- Writing PR bodies outside `pr.md`