vibe-template

vibe-template currently ships as a Cloudflare Worker application served with Wrangler, implemented in JavaScript/TypeScript, and centered on To the Stars: The Last Charter: a server-rendered digital card strategy game with deterministic rivals and automated balance playtests.

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 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.

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.

Game App

• GET / serves the campaign briefing for The Last Charter with house selection, rules summary, command deck preview, and 1000-run balance telemetry.
• GET /new starts a fresh digital card game run using the selected race.
• GET /game serves the playable card session with hand selection, ship loadout, standings, rivals, and reports.
• POST /game/resolve resolves one sealed packet from posted session state and opens a route reward when the run is not complete.
• POST /game/reward claims or skips a route reward before the next playable packet.
• GET /styles.css serves the generated Tailwind stylesheet.
• GET /api/health serves a JSON health response for smoke tests and tooling.
• GET /api/card-playtest serves a deterministic digital card game playtest summary.

The Worker no longer exposes the old mockup-era 4X screens as public game routes. Their underlying source material can remain as reference, but the playable product surface is now the digital card game.

Gameplay Loop

The current game implements a thin but playable digital card loop:

1. Pick one of four houses: The Lumenwood Kin, The Deepforged Holds, The Starling Freeholds, or The Barrow Archive.
2. Each house starts with a ship, fitted component cards, a pressure objective, and a rule that bends the deck.
3. Follow the Aster Gate route through system, rival, forge, council, and final crisis nodes.
4. Each turn, choose up to three command cards from hand.
5. Resolve the sealed packet while deterministic rivals choose their own cards.
6. Commands, events, route nodes, treaties, and ships update frontier, fleet, research, and council pressure tracks.
7. After non-final nodes, claim one offered command card into discard or skip to keep the deck lean.
8. The run ends when a house reaches 165 pressure or the twelfth packet resolves.

The card-game pivot is documented in docs/adrs/implemented/ADR-028-adopt-card-game-adaptation.md; the roguelite campaign extension is documented in docs/adrs/implemented/ADR-030-adopt-roguelite-card-campaign.md. Implementation details and playtest guardrails live in specs/digital-card-game/spec.md.

Source Layout

• src/worker.ts is the Worker entry point and top-level router.
• src/api/ holds API response modules such as health and card playtest endpoints.
• src/game/ holds pure game catalogs, deterministic card rules, simulation reference material, and playtest harnesses.
• src/views/ holds HTML rendering modules for the campaign briefing, playable card session, and reusable card graphics.
• Tests live next to the code they exercise under src/.

Application Screenshot

Refresh this asset manually when the prototype UI changes materially.