goodvibes: Instructions file for Claude Code

Project

goodvibes

goodvibes is a single-command bootstrap for people who want to vibe code with an LLM and not worry about the rest. Run npx goodvibes init (or fork the template), start coding, and everything else — code hygiene, token efficiency, git discipline, CI/CD — happens automatically in the background. It is an open-source Apache 2.0 starter kit targeting complete beginners who use Claude, Copilot, or any other LLM coding tool.

Core Value: One command gives a new vibe coder a production-grade project environment — the LLM is quietly guided to write clean minimal code, tokens are optimized so context never bloats, and git/CI enforces quality gates automatically, all without the user needing to understand any of it.

Constraints

• License: Apache 2.0 — all bundled/forked code must be Apache 2.0 or permissive-compatible (MIT, BSD)
• Zero-config: The installer must work without any user configuration; sensible defaults for everything
• Beginner-first: Every doc, error message, and README section must assume the reader has never opened a terminal before
• Language-agnostic core: CLAUDE.md rules, skills, and CI templates must work for any language/stack
• Headroom bundling: headroom is Python/Rust — the pip installer can pull it as a dependency; the npm installer shells out to pip or documents the pip step clearly

Technology Stack

Recommended Stack

npm CLI Package

• Zero dependencies — keeps npx goodvibes init cold-start lean (~18 ms vs ~35 ms for yargs on Node 20)
• Git-style subcommands (init, update, check) map naturally to its API
• MIT license — fully compatible with Apache 2.0
• 130M+ weekly downloads; the de facto standard for scaffolding CLIs (create-react-app, vue-cli, etc. all use it or Commander descendants)
• Meow is excellent for type inference but lacks subcommand support needed for future goodvibes update command
• ~4 KB gzipped vs. inquirer's much larger footprint — critical for npx cold-start experience
• TypeScript-native, ESM-first — no CommonJS shim pain
• Built-in spinner, group(), and cancellation handling cover 100% of a scaffolding wizard's needs
• Opinionated beautiful output with zero configuration — right for a "zero-config" tool aimed at beginners
• MIT license
• tsup outputs both ESM and CJS from one config — handles the ongoing Node.js dual-module mess without manual effort
• Single bundled file means no runtime resolution cost for npx users
• tsup is MIT licensed
• Adds copy(), mkdirs(), outputFile() with Promises on top of Node's native fs
• Uses graceful-fs internally, preventing EMFILE errors on Windows (too many open file handles)
• Avoids any platform-specific shell commands (cp, xcopy) — pure Node.js, cross-platform by construction
• Promise-based, no callback nesting
• Correct Windows shebang and PATHEXT handling out of the box
• No shell injection risk — args are passed as arrays, not strings
• Sindre Sorhus's most downloaded utility; battle-tested on all three platforms | Package | Version | Purpose | License | |---|---|---|---| | commander | ^13 | Argument parsing, subcommands | MIT | | @clack/prompts | ^0.9 | Interactive wizard UX | MIT | | fs-extra | ^11 | Cross-platform file copy/write | MIT | | execa | ^9 | Subprocess calls (pip, uv, git) | MIT | | tsup | ^8 | Build / bundle | MIT | | typescript | ^5.5 | Language | Apache 2.0 |