create-quiver 0.4.0

package/specs/quiver-v05-readme-adoption-contract/SPEC.md

@@ -0,0 +1,40 @@
+# Quiver v0.5 - README Adoption Contract
+
+**Date:** 2026-04-21
+**Status:** Completed
+
+Slice numbering resets here: this spec starts at `slice-01` and does not continue any previous spec's numbering.
+
+## Objective
+
+Make the root README the adoption contract for Quiver: a new user should understand what Quiver is, install it with the canonical CLI, validate the scaffold, and start the first slice without reading historical implementation notes.
+
+## Scope
+
+### Included
+
+- Reposition the README around `create-quiver` as the primary install path
+- Keep manual `docs-template/` usage as a local development fallback
+- Document the first slice workflow at a high level
+- Separate user adoption guidance from maintainer release guidance
+- Reduce long file inventories and link to the relevant generated docs instead
+
+### Excluded
+
+- CLI behavior changes
+- Generated template content changes
+- Hosted documentation
+- Release automation changes
+
+## Slices
+
+| Slice | Title | Status |
+|-------|-------|--------|
+| 01 | README Adoption Contract | Completed |
+
+## Definition of Done
+
+- The first install command in the README uses `npx create-quiver`
+- The README explains install, doctor validation, first slice workflow, manual fallback, and maintainer commands
+- Commands shown in the README match the current CLI and package scripts
+- The README no longer presents manual template copying as the primary path

package/specs/quiver-v05-readme-adoption-contract/STATUS.md

@@ -0,0 +1,24 @@
+# Quiver v0.5 Spec Status
+
+**Spec:** quiver-v05-readme-adoption-contract
+**Last updated:** 2026-04-21
+
+Slice numbering is local to this spec. The first slice is `slice-01`.
+
+## Status
+
+| Slice | Title | Status | PR | Estimated hours | Actual hours |
+|-------|-------|--------|----|-----------------|--------------|
+| slice-01 | README Adoption Contract | Completed | - | 2 | 2 |
+
+## Progress
+
+- Completed slices: 1 / 1
+- Estimated hours: 2
+- Actual hours: 2
+
+## Blockers
+
+| Slice | Blocker | Since | Action needed |
+|-------|---------|-------|---------------|
+| - | - | - | - |

package/specs/quiver-v05-readme-adoption-contract/slices/slice-01-readme-adoption-contract/slice.json

@@ -0,0 +1,68 @@
+{
+  "slice_id": "slice-01-readme-adoption-contract",
+  "ticket": "QUIVER-01",
+  "type": "docs",
+  "title": "README Adoption Contract",
+  "objective": "Rewrite the root README so it presents Quiver as a CLI-first adoption workflow rather than a manual docs-template copy.",
+  "description": "The existing README mixes the historical manual template flow with the newer create-quiver installer. This slice makes the README a concise adoption contract for users and maintainers without changing runtime behavior.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "develop",
+    "branch_slug": "readme-adoption-contract",
+    "branch_name": "docs/QUIVER-01-readme-adoption-contract"
+  },
+  "must": [
+    "Make `npx create-quiver` the primary quick-start path",
+    "Document `create-quiver doctor` immediately after installation",
+    "Explain the first slice workflow at a high level",
+    "Move release guidance into a maintainer-focused section",
+    "Keep manual `docs-template/` use as a fallback or local development path",
+    "Avoid long duplicated file inventories in the root README"
+  ],
+  "not_included": [
+    "Changes to CLI behavior",
+    "Changes to generated project templates",
+    "Hosted docs or website work"
+  ],
+  "acceptance": [
+    "A new reader can install, validate, and begin slice work from the README alone",
+    "The README's commands match the current CLI help and package scripts",
+    "Manual copy instructions no longer appear before the CLI quick start",
+    "Maintainer release instructions are separated from user onboarding",
+    "The README links to AI, support, and troubleshooting docs instead of duplicating their full contents",
+    "The change is limited to README and spec traceability files"
+  ],
+  "files": [
+    "README.md",
+    "specs/quiver-v05-readme-adoption-contract/SPEC.md",
+    "specs/quiver-v05-readme-adoption-contract/STATUS.md",
+    "specs/quiver-v05-readme-adoption-contract/EVIDENCE_REPORT.md",
+    "specs/quiver-v05-readme-adoption-contract/slices/slice-01-readme-adoption-contract/slice.json"
+  ],
+  "tests": [
+    "CLI help command check",
+    "release helper help command check",
+    "package.json script existence check",
+    "README target link existence check",
+    "git diff whitespace check"
+  ],
+  "documentation": [
+    "specs/quiver-v05-readme-adoption-contract/SPEC.md",
+    "specs/quiver-v05-readme-adoption-contract/STATUS.md",
+    "specs/quiver-v05-readme-adoption-contract/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "quiver-v04-zero-friction-installation"
+  ],
+  "assumptions": [
+    "The README should stay concise and point to detailed generated docs",
+    "The canonical install path is the npm CLI entrypoint"
+  ],
+  "estimated_hours": 2,
+  "actual_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": "2026-04-21T00:00:00Z",
+  "started_at": "2026-04-21T00:00:00Z",
+  "completed_at": "2026-04-21T00:00:00Z"
+}

package/specs/quiver-v06-release-readiness/EVIDENCE_REPORT.md

@@ -0,0 +1,23 @@
+# Quiver v0.6 Evidence Report
+
+**Spec:** quiver-v06-release-readiness
+**Last updated:** 2026-04-21
+**Status:** Completed
+
+## Summary
+
+| Slice | Acceptance criteria | Status | Evidence |
+|-------|---------------------|--------|----------|
+| slice-01 | 6 | Completed | Release helper now supports `--publish-current`, changelog has `0.4.0`, and README documents the exact preflight and publish steps |
+
+## Evidence by Slice
+
+- `bash -n scripts/release-quiver.sh`
+- `git diff --check`
+- `node -e "const fs=require('fs'); JSON.parse(fs.readFileSync('specs/quiver-v06-release-readiness/slices/slice-01-first-npm-release-readiness/slice.json','utf8'))"`
+
+## Preflight Notes
+
+- `npm whoami` failed with `ENEEDAUTH`; npm login is required before publish.
+- `npm view create-quiver version` failed with DNS/network resolution against `registry.npmjs.org`; registry reachability must be verified before publish.
+- Current package metadata is `create-quiver@0.4.0`.

package/specs/quiver-v06-release-readiness/SPEC.md

@@ -0,0 +1,40 @@
+# Quiver v0.6 - Release Readiness
+
+**Date:** 2026-04-21
+**Status:** Completed
+
+Slice numbering resets here: this spec starts at `slice-01` and does not continue any previous spec's numbering.
+
+## Objective
+
+Prepare Quiver for its first public npm release without accidentally bumping past the intended initial version.
+
+## Scope
+
+### Included
+
+- Align the release helper with first-release needs
+- Update the changelog from `Unreleased` to the intended release version
+- Validate the local package, installer smoke, release dry run, and npm prereqs
+- Document the publish steps and post-release verification
+
+### Excluded
+
+- Publishing the package during spec preparation
+- Changing CLI behavior
+- Changing generated project templates
+- Hosted documentation or marketing work
+
+## Slices
+
+| Slice | Title | Status |
+|-------|-------|--------|
+| 01 | First npm Release Readiness | Completed |
+
+## Definition of Done
+
+- The release helper can validate and publish the current package version without forcing an unintended patch bump
+- `CHANGELOG.md` has a `0.4.0` release entry dated 2026-04-21 and a fresh `Unreleased` section
+- npm auth and package-name availability are checked before publish
+- Local package, installer, and release dry-run validations pass
+- The publish command is explicit and not run as part of this slice unless requested separately

package/specs/quiver-v06-release-readiness/STATUS.md

@@ -0,0 +1,24 @@
+# Quiver v0.6 Spec Status
+
+**Spec:** quiver-v06-release-readiness
+**Last updated:** 2026-04-21
+
+Slice numbering is local to this spec. The first slice is `slice-01`.
+
+## Status
+
+| Slice | Title | Status | PR | Estimated hours | Actual hours |
+|-------|-------|--------|----|-----------------|--------------|
+| slice-01 | First npm Release Readiness | Completed | - | 2 | 2 |
+
+## Progress
+
+- Completed slices: 1 / 1
+- Estimated hours: 2
+- Actual hours: 2
+
+## Blockers
+
+| Slice | Blocker | Since | Action needed |
+|-------|---------|-------|---------------|
+| - | - | - | - |

package/specs/quiver-v06-release-readiness/slices/slice-01-first-npm-release-readiness/slice.json

@@ -0,0 +1,71 @@
+{
+  "slice_id": "slice-01-first-npm-release-readiness",
+  "ticket": "QUIVER-01",
+  "type": "release",
+  "title": "First npm Release Readiness",
+  "objective": "Prepare the repository for publishing the first public `create-quiver` npm package at the intended current version.",
+  "description": "The package is functionally ready, but the current release helper always runs `npm version patch` when publishing. That would publish `0.4.1` as the first public release instead of the current `0.4.0`. This slice updates the release contract, changelog, and validation path so publishing is explicit and version-safe.",
+  "git": {
+    "branch_type": "release",
+    "base_branch": "develop",
+    "branch_slug": "first-npm-release-readiness",
+    "branch_name": "release/QUIVER-01-first-npm-release-readiness"
+  },
+  "must": [
+    "Update `scripts/release-quiver.sh` so maintainers can publish the current version intentionally without forcing a patch bump",
+    "Update `CHANGELOG.md` so the current release notes move from `Unreleased` to `0.4.0 - 2026-04-21`",
+    "Keep `Unreleased` available for future changes",
+    "Document the exact preflight checks for npm auth, package-name availability, package smoke, installer smoke, and release dry run",
+    "Run local validations but do not publish unless a separate explicit release request is made"
+  ],
+  "not_included": [
+    "Publishing to npm",
+    "Changing package name or CLI behavior",
+    "Creating hosted docs or release marketing",
+    "Changing generated project templates"
+  ],
+  "acceptance": [
+    "Maintainers can publish `create-quiver@0.4.0` without an unintended version bump",
+    "`CHANGELOG.md` has a dated `0.4.0` section and a fresh `Unreleased` section",
+    "Release dry run still validates installer and package smoke checks",
+    "The spec records npm auth and registry reachability as required preflight gates",
+    "The publish step remains explicit and separate from this preparation work",
+    "No npm publish command is executed during this slice"
+  ],
+  "files": [
+    "scripts/release-quiver.sh",
+    "CHANGELOG.md",
+    "README.md",
+    "specs/quiver-v06-release-readiness/SPEC.md",
+    "specs/quiver-v06-release-readiness/STATUS.md",
+    "specs/quiver-v06-release-readiness/EVIDENCE_REPORT.md",
+    "specs/quiver-v06-release-readiness/slices/slice-01-first-npm-release-readiness/slice.json"
+  ],
+  "tests": [
+    "npm auth and package-name preflight are documented in the README",
+    "package smoke",
+    "installer smoke",
+    "release dry run",
+    "git diff whitespace check"
+  ],
+  "documentation": [
+    "specs/quiver-v06-release-readiness/SPEC.md",
+    "specs/quiver-v06-release-readiness/STATUS.md",
+    "specs/quiver-v06-release-readiness/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "quiver-v05-readme-adoption-contract"
+  ],
+  "assumptions": [
+    "The first public release should use the current package version `0.4.0`",
+    "The package name remains `create-quiver` unless npm availability proves otherwise",
+    "Publishing requires separate explicit approval after this readiness slice is merged"
+  ],
+  "estimated_hours": 2,
+  "actual_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": "2026-04-21T00:00:00Z",
+  "started_at": "2026-04-21T00:00:00Z",
+  "completed_at": "2026-04-21T00:00:00Z"
+}

package/src/create-quiver/index.js

@@ -0,0 +1,329 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+function printUsage() {
+  console.log(`Usage:
+  npx create-quiver [options]
+  npx create-quiver doctor [options]
+
+Options:
+  -n, --name <project-name>   Project name to generate
+  -d, --dir <target-dir>      Target directory to scaffold into or inspect
+  -y, --yes                   Skip prompts and use the provided inputs
+  -h, --help                  Show this help message
+
+Examples:
+  npx create-quiver --name "My Project"
+  npx create-quiver --name "My Project" --dir ./my-project
+  npx create-quiver doctor --dir ./my-project
+  node bin/create-quiver.js doctor --dir ./my-project
+`);
+}
+
+function parseArgs(argv) {
+  const result = {
+    help: false,
+    force: false,
+    mode: 'init',
+    projectName: '',
+    targetDir: '.',
+  };
+
+  const args = [...argv];
+  if (args[0] === 'doctor') {
+    result.mode = 'doctor';
+    args.shift();
+  }
+
+  const positional = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === '-h' || arg === '--help') {
+      result.help = true;
+      continue;
+    }
+
+    if (arg === '-y' || arg === '--yes') {
+      result.force = true;
+      continue;
+    }
+
+    if (arg === '--doctor') {
+      result.mode = 'doctor';
+      continue;
+    }
+
+    if (arg === '-n' || arg === '--name' || arg === '--project-name') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --name'));
+      }
+      result.projectName = value;
+      continue;
+    }
+
+    if (arg === '-d' || arg === '--dir' || arg === '--target') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --dir'));
+      }
+      result.targetDir = value;
+      continue;
+    }
+
+    if (arg.startsWith('-')) {
+      throw new Error(formatError(`unknown flag: ${arg}`));
+    }
+
+    positional.push(arg);
+  }
+
+  if (result.mode === 'init') {
+    if (!result.projectName && positional.length > 0) {
+      result.projectName = positional.shift();
+    }
+
+    if (positional.length > 0) {
+      result.targetDir = positional.shift();
+    }
+  } else {
+    if (positional.length > 0) {
+      result.targetDir = positional.shift();
+    }
+  }
+
+  if (positional.length > 0) {
+    throw new Error(formatError('too many positional arguments'));
+  }
+
+  return result;
+}
+
+function toProjectSlug(projectName) {
+  return projectName
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'quiver-project';
+}
+
+function runCommand(command, args, options = {}) {
+  return execFileSync(command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'inherit'],
+    ...options,
+  });
+}
+
+function packTemplate(packageRoot, tempRoot) {
+  const packDir = path.join(tempRoot, 'pack');
+  const extractDir = path.join(tempRoot, 'extract');
+  const npmCache = path.join(tempRoot, 'npm-cache');
+
+  fs.mkdirSync(packDir, { recursive: true });
+  fs.mkdirSync(extractDir, { recursive: true });
+  fs.mkdirSync(npmCache, { recursive: true });
+
+  const packOutput = runCommand('npm', ['pack', '--json', '--pack-destination', packDir], {
+    cwd: packageRoot,
+    env: {
+      ...process.env,
+      npm_config_cache: npmCache,
+    },
+  });
+
+  const packInfo = JSON.parse(packOutput.trim());
+  const tarballPath = path.join(packDir, packInfo[0].filename);
+
+  if (!fs.existsSync(tarballPath)) {
+    throw new Error(formatError(`pack output not found at ${tarballPath}`));
+  }
+
+  runCommand('tar', ['-xzf', tarballPath, '-C', extractDir]);
+
+  return path.join(extractDir, 'package');
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function copyTemplate(templateRoot, targetDir) {
+  const docsTemplateDir = path.join(targetDir, 'docs-template');
+
+  if (fs.existsSync(docsTemplateDir)) {
+    throw new Error(formatError(`docs-template already exists at ${docsTemplateDir}`));
+  }
+
+  fs.cpSync(templateRoot, docsTemplateDir, { recursive: true });
+
+  return docsTemplateDir;
+}
+
+function runInitDocs(repoRoot, projectName) {
+  runCommand('bash', ['docs-template/scripts/init-docs.sh', projectName], {
+    cwd: repoRoot,
+  });
+}
+
+function listGeneratedSpecDirs(projectRoot) {
+  const specsDir = path.join(projectRoot, 'specs');
+
+  if (!fs.existsSync(specsDir)) {
+    return [];
+  }
+
+  return fs.readdirSync(specsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((entry) => entry !== '[project-name]' && !entry.startsWith('quiver-'));
+}
+
+function assertFilesExist(root, relativePaths) {
+  return relativePaths.filter((relativePath) => !fs.existsSync(path.join(root, relativePath)));
+}
+
+function assertExecutablesExist(root, relativePaths) {
+  return relativePaths.filter((relativePath) => {
+    const absolutePath = path.join(root, relativePath);
+
+    if (!fs.existsSync(absolutePath)) {
+      return true;
+    }
+
+    const mode = fs.statSync(absolutePath).mode;
+    return (mode & 0o111) === 0;
+  });
+}
+
+function loadPackageJson(projectRoot) {
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+
+  if (!fs.existsSync(packageJsonPath)) {
+    throw new Error(formatError(`missing package.json in ${projectRoot}`));
+  }
+
+  return JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+}
+
+function runDoctor(targetDir) {
+  const projectRoot = path.resolve(process.cwd(), targetDir);
+
+  if (!fs.existsSync(projectRoot)) {
+    throw new Error(formatError(`target directory does not exist: ${projectRoot}`));
+  }
+
+  const generatedSpecs = listGeneratedSpecDirs(projectRoot);
+  if (generatedSpecs.length !== 1) {
+    throw new Error(formatError(`expected exactly one generated spec directory, found ${generatedSpecs.length || 0}`));
+  }
+
+  const projectSlug = generatedSpecs[0];
+  const requiredFiles = [
+    'README.md',
+    'docs/INDEX.md',
+    'docs/CONTEXTO.md',
+    'docs/WORKFLOW.md',
+    'docs/SUPPORT_MATRIX.md',
+    'docs/TROUBLESHOOTING.md',
+    'docs/TESTING_GUIDE_FOR_AI.md',
+    'docs/ai/PRINCIPLES.md',
+    'docs/ai/RULES.yaml',
+    'docs/ai/LESSONS.md',
+    `specs/${projectSlug}/SPEC.md`,
+    `specs/${projectSlug}/STATUS.md`,
+    `specs/${projectSlug}/EVIDENCE_REPORT.md`,
+    'package.json',
+    '.github/pull_request_template.md',
+    '.github/ISSUE_TEMPLATE/bug_report.md',
+    '.github/ISSUE_TEMPLATE/feature_request.md',
+    '.github/workflows/ci.yml',
+  ];
+
+  const requiredExecutables = [
+    'tools/scripts/start-slice.sh',
+    'tools/scripts/check-slice-readiness.sh',
+    'tools/scripts/check-pr-readiness.sh',
+    'tools/scripts/cleanup-slice.sh',
+    'tools/scripts/check-scope.sh',
+  ];
+
+  const missingFiles = assertFilesExist(projectRoot, requiredFiles);
+  const nonExecutableScripts = assertExecutablesExist(projectRoot, requiredExecutables);
+  const pkg = loadPackageJson(projectRoot);
+  const requiredScripts = ['check:slice', 'check:pr', 'start:slice', 'cleanup:slice'];
+  const missingScripts = requiredScripts.filter((name) => typeof pkg.scripts?.[name] !== 'string');
+
+  const problems = [
+    ...missingFiles.map((file) => `missing file: ${file}`),
+    ...nonExecutableScripts.map((file) => `missing executable bit: ${file}`),
+    ...missingScripts.map((name) => `missing package.json script: ${name}`),
+  ];
+
+  if (problems.length > 0) {
+    throw new Error(formatError(`doctor failed:\n- ${problems.join('\n- ')}`));
+  }
+
+  console.log(`Quiver doctor passed for ${projectRoot}`);
+  console.log(`Generated project slug: ${projectSlug}`);
+  console.log('Next steps:');
+  console.log(`- Run ${path.join(projectRoot, 'tools', 'scripts', 'start-slice.sh')} ${path.join(projectRoot, 'specs', projectSlug, 'slices', 'slice-template', 'slice.json')}`);
+  console.log(`- Validate a slice with ${path.join(projectRoot, 'tools', 'scripts', 'check-slice-readiness.sh')}`);
+  console.log(`- Validate the PR gate with ${path.join(projectRoot, 'tools', 'scripts', 'check-pr-readiness.sh')}`);
+}
+
+function printInitNextSteps(targetDir, projectName) {
+  const projectSlug = toProjectSlug(projectName);
+
+  console.log('');
+  console.log('Next steps:');
+  console.log(`- Review ${path.join(targetDir, 'docs', 'INDEX.md')}`);
+  console.log(`- Review ${path.join(targetDir, 'docs', 'WORKFLOW.md')}`);
+  console.log(`- Create your first slice from ${path.join(targetDir, 'specs', projectSlug, 'slices', 'slice-template', 'slice.json')}`);
+  console.log(`- Launch slice work with ${path.join(targetDir, 'tools', 'scripts', 'start-slice.sh')}`);
+}
+
+async function run(argv) {
+  const args = parseArgs(argv);
+
+  if (args.help) {
+    printUsage();
+    return;
+  }
+
+  if (args.mode === 'doctor') {
+    runDoctor(args.targetDir);
+    return;
+  }
+
+  const packageRoot = path.resolve(__dirname, '../..');
+  const targetDir = path.resolve(process.cwd(), args.targetDir);
+  const projectName = args.projectName || path.basename(targetDir) || 'Quiver Project';
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-create-'));
+
+  try {
+    ensureDir(targetDir);
+
+    const templateRoot = packTemplate(packageRoot, tempRoot);
+    copyTemplate(templateRoot, targetDir);
+    runInitDocs(targetDir, projectName);
+
+    console.log(`Installed Quiver into ${targetDir}`);
+    printInitNextSteps(targetDir, projectName);
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+module.exports = {
+  run,
+};