vibe-template

vibe-template currently ships as a Cloudflare Worker application served with Wrangler, implemented in JavaScript/TypeScript, and centered on server-rendered HTML with a small JSON API stub.

This is a template for my vibecoding projects and it captures what I consider my best practices so I don't have to repeat them for each experiment.

The repo vendors ASDLC reference material in .asdlc/ as local guidance instead of recreating it per project. Repo-specific truth lives in ARCHITECTURE.md, specs/, and docs/adrs/: generated code still needs to match those documents, and passing CI alone is not enough.

Local development in this repo targets macOS. Other platforms may need script and tooling adjustments before the baseline workflow works as documented.

Documentation

• Development setup and local CI: docs/development.md
• Architecture decisions: docs/adrs/README.md
• Feature and architecture specs: specs/README.md
• Agent behavior and project rules: AGENTS.md
• Partial-upgrade capability kits: .capabilities/

Runtime

• Run nvm use before npm install or any other development command so your shell picks up the repo-pinned Node.js version from .nvmrc and stays close to the expected npm baseline.
• Install dependencies with npm install.
• npm install also configures the repo-managed pre-push hook so git push runs npm run quality:gate:fast before code leaves your machine.
• The exact project Node.js version is pinned in package.json and mirrored in .nvmrc for nvm users, and CI reads the package.json value directly.
• npm is also pinned exactly in package.json; local development is expected to use nvm use, and CI upgrades npm to the exact repo pin when the bundled npm version differs.
• Copy .dev.vars.example to .dev.vars before running projects that need local secrets.
• Use repo-pinned CLI tools through npx, including npx wrangler for Cloudflare-based experiments.
• Start the stub Worker with npm run dev, then open http://127.0.0.1:8787.
• Rebuild the generated Tailwind stylesheet manually with npm run build:css when needed.

Verification

• Run the fast local gate with npm run quality:gate:fast during normal iteration.
• Run the baseline repo gate with npm run quality:gate.
• Run the containerized local workflow with npm run ci:local.
• The repo-managed pre-push hook runs npm run quality:gate:fast automatically after npm install.
• If local Agent CI warns about No such remote 'origin', set GITHUB_REPO=owner/repo in .env.agent-ci.
• Retry a paused local CI run with npm run ci:local:retry -- --name <runner-name>.
• Install the pinned Playwright browser with npm run playwright:install.
• Run unit tests from colocated src/**/*.test.ts files with npm test.
• Run browser tests from colocated src/**/*.e2e.ts files with npm run e2e.
• Run mutation tests against runtime src/**/*.ts files with npm run mutation.

Capability Kits

Use .capabilities/ when another project needs one template practice without adopting the whole starter. Each kit is a reviewable partial-upgrade guide with a README, manifest, package-manager recipe, copyable files, and validation checks.

To apply a kit to another repo:

1. Pick the smallest matching kit from .capabilities/README.md.
2. Read the kit README and manifest.json.
3. Follow the target package-manager recipe under recipes/.
4. Copy or merge files from files/ without overwriting target-project conventions.
5. Ask before applying optional adjacent setup such as creating a GitHub Actions workflow.
6. Run the kit checks and the target repo's normal quality gate.

For existing projects where the right kit set is unclear, start with the negotiation prompt in .capabilities/README.md. It asks an agent to inspect the target repo, present a checkbox-style capability pull plan, and wait for approval before editing files.

Starter App

• GET / serves a minimal editorial Worker stub with a route index and a primary health-probe link.
• GET /styles.css serves the generated Tailwind stylesheet.
• GET /api/health serves a JSON health response for smoke tests and tooling.

Source Layout

• src/worker.ts is the Worker entry point and top-level router.
• src/api/ holds API response modules such as the health endpoint.
• src/views/ holds HTML rendering modules for the starter UI.
• Tests live next to the code they exercise under src/.

Application Screenshot

Refresh this asset manually when the starter UI changes materially.