create-quiver 0.4.0 → 0.6.0

package/README.md

@@ -4,56 +4,108 @@ Quiver is a CLI-first documentation workflow for projects that use specs, slices
 
 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
+## Developer Onboarding Flow
 
-Create or update a project with the installer:
+Use this flow when adopting Quiver in an existing project or starting a new one.
+
+### 1. Install Quiver
+
+Run Quiver from the project where the workflow will live:
 
 ```bash
-npx create-quiver --name "Project Name" --dir ./target-repo
+cd /path/to/your-project
+npx create-quiver --name "Project Name"
 ```
 
-To install into the current directory, omit `--dir`:
+Do not install Quiver globally. Running it with `npx` from the project root keeps the generated docs, specs, and scripts in the right repository.
+
+If your team wants to pin the Quiver version in the project, install it as a devDependency:
 
 ```bash
+npm install --save-dev create-quiver
 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
+To initialize a different directory from outside the project, pass `--dir` explicitly. Quote paths that contain spaces:
 
-See the generated `docs/SUPPORT_MATRIX.md` for the detailed support contract.
+```bash
+npx create-quiver --name "Project Name" --dir "/Users/me/My Project"
+```
 
-## Validate
+### 2. Analyze And Validate
 
-After installation, run the doctor:
+Run the local analyzer and then validate the generated contract:
 
 ```bash
+npx create-quiver analyze --dir ./target-repo
 npx create-quiver doctor --dir ./target-repo
 ```
 
-The doctor checks the generated project contract and prints the next workflow steps.
+If you are working in the current directory, use `--dir .`.
+
+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.
+
+### 3. Upgrade Existing Projects
+
+If the project already had Quiver from an older version, upgrade it from the project root:
+
+```bash
+cd /path/to/your-project
+npx create-quiver migrate --dir .
+npx create-quiver analyze --dir .
+npx create-quiver doctor --dir .
+```
+
+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 .
+```
+
+### 4. Ask The AI To Prepare Context
+
+Open your AI agent in the target project and run this short handoff:
+
+```text
+Read docs/AI_ONBOARDING_PROMPT.md and execute it.
+Do not modify product code unless I explicitly authorize it.
+Prepare the project context docs and report assumptions, risks, and files changed.
+```
+
+The AI should use the scan artifacts to prepare `docs/AI_CONTEXT.md`, `docs/CONTEXTO.md`, `docs/STATUS.md`, and the initial project spec. The developer should review those documentation changes before implementation work starts.
 
-## First Slice Workflow
+### 5. Start The First Slice
 
-After the scaffold is valid:
+After the context docs are reviewed:
 
-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.
+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>`.
+4. Make one commit per slice.
+5. Open one PR per spec.
 
 Slice numbering is local to each spec: every new spec starts at `slice-01`.
 
+## 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.
+
 ## What Gets Generated
 
 Quiver generates a project-local workflow under:
 
 - `docs/` for project context, workflow, support, troubleshooting, and AI guidance
+- `docs/PROJECT_SCAN.json` and `docs/PROJECT_MAP.md` after `create-quiver analyze`
+- `docs/AI_ONBOARDING_PROMPT.md` as the generated handoff prompt for the AI agent
 - `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
@@ -70,10 +122,11 @@ Use the manual flow only when developing Quiver locally or testing a template ch
 ```
 
 The CLI path is the supported adoption path for users.
+For analyzed projects, the agent handoff prompt lives at `docs/AI_ONBOARDING_PROMPT.md` in the generated project.
 
 ## 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.
+Read `README_FOR_AI.md` before working in this repository or in a generated project. In generated projects, `docs/AI_CONTEXT.md` is the first agent context file to read, followed by `docs/AI_ONBOARDING_PROMPT.md`, `docs/CONTEXTO.md`, and `docs/WORKFLOW.md`.
 
 ## For Maintainers
 
@@ -108,6 +161,7 @@ For a first release, prefer `--publish-current` so the published package stays a
 ## References
 
 - [AI guide](./README_FOR_AI.md)
+- [AI context template](./docs/AI_CONTEXT.md.template)
 - [Support matrix template](./docs/SUPPORT_MATRIX.md.template)
 - [Troubleshooting template](./docs/TROUBLESHOOTING.md.template)
 - [Changelog](./CHANGELOG.md)

package/README_FOR_AI.md

@@ -2,10 +2,16 @@
 
 Use this guide when initializing a new project from the template or when explaining the workflow to another agent.
 
+The first AI job in a generated project is context preparation, not product implementation.
+
 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 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`.
 Maintain release notes and package publishing with `scripts/release-quiver.sh`.
+The primary generated project context for agents is `docs/AI_CONTEXT.md`.
+If a generated project has been analyzed, the exact agent handoff prompt is `docs/AI_ONBOARDING_PROMPT.md`.
 
 ## Core Rules
 
@@ -13,6 +19,9 @@ Maintain release notes and package publishing with `scripts/release-quiver.sh`.
 - 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 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 support contract lives in `docs/SUPPORT_MATRIX.md` and `docs/TROUBLESHOOTING.md`.
 
 ## Initialization Flow
@@ -25,6 +34,8 @@ Maintain release notes and package publishing with `scripts/release-quiver.sh`.
 ```
 
 3. Tell the user to edit:
+  - `docs/AI_CONTEXT.md`
+  - `docs/AI_ONBOARDING_PROMPT.md`
   - `docs/CONTEXTO.md`
   - `docs/STATUS.md`
   - `docs/SUPPORT_MATRIX.md`
@@ -35,6 +46,8 @@ Maintain release notes and package publishing with `scripts/release-quiver.sh`.
 
 - `docs/`
 - `docs/ai/`
+- `docs/AI_CONTEXT.md`
+- `docs/AI_ONBOARDING_PROMPT.md`
 - `specs/{{PROJECT_SLUG}}/`
 - `tools/scripts/`
 - `docs/SEARCH.md`
@@ -59,15 +72,21 @@ Maintain release notes and package publishing with `scripts/release-quiver.sh`.
 
 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
+1. Fill in `docs/AI_CONTEXT.md`
+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>`
+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>`
+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.
 
@@ -78,6 +97,7 @@ Bootstrap note: `start-slice.sh` should resolve paths canonically, prefer a loca
 - `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
+- `docs/AI_ONBOARDING_PROMPT.md` after analysis
 
 ## Good Defaults
 

package/docs/AI_CONTEXT.md.template

@@ -0,0 +1,59 @@
+# {{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.
+
+## What This Project Is
+
+[Short project summary.]
+
+## 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`
+
+## Critical Rules
+
+- One slice maps to one commit.
+- One spec maps to one PR.
+- Slice numbering resets inside each spec.
+- Do not invent files that the bootstrap did not generate.
+- Use canonical paths when a path matters.
+- 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`
+- `specs/{{PROJECT_SLUG}}/EVIDENCE_REPORT.md`
+- the slice JSON and optional slice PR note
+- any docs whose behavior changed
+
+## If You Need More Context
+
+Read `docs/CONTEXTO.md` for the human project overview and `docs/WORKFLOW.md` for the execution contract.
+
+## If The Environment Fails
+
+Use `docs/TROUBLESHOOTING.md` before changing the workflow itself.

package/docs/AI_ONBOARDING_PROMPT.md.template

@@ -0,0 +1,56 @@
+# {{PROJECT_NAME}} AI Onboarding Prompt
+
+**Date:** {{FECHA}}
+**Status:** {{ESTADO}}
+
+You are the onboarding agent for this project. Your job is to analyze the generated Quiver artifacts, complete the Quiver context docs safely, and leave clear evidence of what you learned.
+
+## Read First
+
+1. `docs/AI_CONTEXT.md`
+2. `docs/PROJECT_SCAN.json`
+3. `docs/PROJECT_MAP.md`
+4. `docs/CONTEXTO.md`
+5. `docs/WORKFLOW.md`
+6. `specs/{{PROJECT_SLUG}}/SPEC.md`
+7. `specs/{{PROJECT_SLUG}}/STATUS.md`
+8. `specs/{{PROJECT_SLUG}}/EVIDENCE_REPORT.md`
+
+## Mission
+
+- Use the analyzer outputs to understand the repository instead of guessing.
+- 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.
+
+## Hard Constraints
+
+- Do not read or expose secret values from `.env`, credential files, tokens, SSH keys, or private config.
+- Skip files that look like secrets or generated build output.
+- Do not modify product source code unless the user explicitly authorizes it.
+- Do not invent missing facts. If something is unclear, record the uncertainty.
+- Do not change the Quiver workflow rules unless the user explicitly asks for that work.
+
+## Tasks
+
+1. Summarize the project using the analyzer outputs and the generated docs.
+2. Update `docs/AI_CONTEXT.md` with the working contract for agents.
+3. Update `docs/CONTEXTO.md` with the human-readable project overview.
+4. Update `docs/STATUS.md` with the initial state and open questions.
+5. If needed, refine `specs/{{PROJECT_SLUG}}/SPEC.md` only to align the onboarding spec with observed reality.
+6. Record the files you inspected, the files you changed, and the assumptions you made.
+
+## Validation
+
+- Cite the generated scan artifacts when making claims.
+- Note any skipped paths or missing signals.
+- Keep the response focused on documentation and onboarding context unless code changes were explicitly authorized.
+
+## Final Report
+
+Return:
+
+- Files changed
+- Key assumptions
+- Uncertainties or risks
+- Validation performed

package/docs/CONTEXTO.md.template

@@ -42,4 +42,4 @@ Backend:
 
 ## Next Step
 
-Read `INDEX.md` to navigate the rest of the documentation.
+Read `AI_CONTEXT.md` first if you are an AI agent. Otherwise read `INDEX.md` to navigate the rest of the documentation.

package/docs/DOCUMENTATION_GUIDE.md.template

@@ -6,13 +6,14 @@
 ## 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`
+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`
 
 ## Update Rules
 
@@ -23,6 +24,7 @@
 ## Where Things Go
 
 - Project overview: `docs/CONTEXTO.md`
+- Agent context pack: `docs/AI_CONTEXT.md`
 - Progress: `docs/STATUS.md`
 - Implementation workflow: `docs/WORKFLOW.md`
 - Support contract: `docs/SUPPORT_MATRIX.md`

package/docs/INDEX.md.template

@@ -5,6 +5,8 @@
 ## Start Here
 
 - **Context** - `./CONTEXTO.md`
+- **AI Context** - `./AI_CONTEXT.md`
+- **AI Onboarding Prompt** - `./AI_ONBOARDING_PROMPT.md`
 - **Workflow** - `./WORKFLOW.md`
 - **Support Matrix** - `./SUPPORT_MATRIX.md`
 - **Troubleshooting** - `./TROUBLESHOOTING.md`
@@ -28,6 +30,8 @@
 ```text
 docs/
 ├── INDEX.md
+├── AI_CONTEXT.md
+├── AI_ONBOARDING_PROMPT.md
 ├── CONTEXTO.md
 ├── STATUS.md
 ├── WORKFLOW.md

package/docs/WORKFLOW.md.template

@@ -15,6 +15,7 @@ This document is the canonical implementation workflow for the project.
 - 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.
+- The AI onboarding prompt generated after analysis is the handoff for agents that need project context before editing.
 
 ## Planning
 
@@ -23,7 +24,9 @@ This document is the canonical implementation workflow for the project.
 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.
+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.
 
 ## Execution
 
@@ -40,6 +43,7 @@ This document is the canonical implementation workflow for the project.
 ## Support Contract
 
 - 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.
 - Keep both files linked from the root README and this workflow doc.
 
@@ -50,6 +54,8 @@ Use multiple agents only when the write sets do not overlap and the coordination
 ## References
 
 - `GITFLOW_PR_GUIDE.md`
+- `AI_CONTEXT.md`
+- `AI_ONBOARDING_PROMPT.md`
 - `SUPPORT_MATRIX.md`
 - `TROUBLESHOOTING.md`
 - `MULTI_AGENT_WORKFLOW.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",
@@ -12,6 +12,7 @@
     "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",
     "release:quiver": "bash scripts/release-quiver.sh"

package/package.template.json

@@ -5,6 +5,7 @@
     "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",
+    "migrate": "bash tools/scripts/migrate-project.sh"
   }
 }