{"_id":"@ddnet-repo/vibescript","name":"@ddnet-repo/vibescript","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@ddnet-repo/vibescript","version":"1.0.0","description":"Governance tooling that constrains AI-assisted coding through directives, manifests, ownership rules, and compliance checks","type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"vibescript":"dist/cli/main.js"},"scripts":{"build":"tsc","dev":"tsc --watch","test":"vitest","lint":"eslint src/**/*.ts","vibe:check":"node dist/cli/main.js check","vibe:guard":"node dist/cli/main.js guard","prepublishOnly":"npm run build"},"keywords":["ai","governance","typescript","claude","vibe","directives","compliance"],"author":{"name":"burtbyproxy","email":"steve@datadigital.net"},"repository":{"type":"git","url":"git+https://github.com/burtbyproxy/vibescript.git"},"bugs":{"url":"https://github.com/burtbyproxy/vibescript/issues"},"homepage":"https://github.com/burtbyproxy/vibescript#readme","license":"MIT","devDependencies":{"@types/node":"^20.10.0","typescript":"^5.3.0","vitest":"^1.0.0"},"dependencies":{"commander":"^12.0.0","minimatch":"^9.0.0","picocolors":"^1.0.0"},"engines":{"node":">=18.0.0"},"_id":"@ddnet-repo/vibescript@1.0.0","gitHead":"10fd5aa61ff81ad788377dcf8afcc112b8c39183","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-HtBdPCLVuymxADzL8Rc2KwlgwPzy98eDkBQF89D2NJA5mWCwmfs3X7P3ugH2oovATzCQEHd5L0A+1yMTXQo1eg==","shasum":"1c270025e80f1e03916ca37a9b91a25379a5333b","tarball":"https://registry.npmjs.org/@ddnet-repo/vibescript/-/vibescript-1.0.0.tgz","fileCount":69,"unpackedSize":153541,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDeRADdDaj10B8nfwSHcV7W7FdhCI732i6bfHs/wG7imQIhAORFACqif/ebPhnbvN8dg3g0Xg1twopVHPugItQw+U6n"}]},"_npmUser":{"name":"steve_ddnet","email":"steve@datadigital.net"},"directories":{},"maintainers":[{"name":"steve_ddnet","email":"steve@datadigital.net"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/vibescript_1.0.0_1769027137694_0.39293869669501236"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-21T20:25:37.584Z","1.0.0":"2026-01-21T20:25:37.839Z","modified":"2026-01-21T20:25:38.293Z"},"maintainers":[{"name":"steve_ddnet","email":"steve@datadigital.net"}],"description":"Governance tooling that constrains AI-assisted coding through directives, manifests, ownership rules, and compliance checks","homepage":"https://github.com/burtbyproxy/vibescript#readme","keywords":["ai","governance","typescript","claude","vibe","directives","compliance"],"repository":{"type":"git","url":"git+https://github.com/burtbyproxy/vibescript.git"},"author":{"name":"burtbyproxy","email":"steve@datadigital.net"},"bugs":{"url":"https://github.com/burtbyproxy/vibescript/issues"},"license":"MIT","readme":"# VibeScript\n\n**Governance tooling for AI-assisted coding in TypeScript/JavaScript projects.**\n\nPut guardrails on Claude, Copilot, and other AI coding assistants so they can't go rogue in your codebase.\n\n> **Language Support**: VibeScript is designed for **TypeScript and JavaScript** projects using Node.js. The governance files use `.vibe.ts` extensions and the tooling integrates with npm/pnpm workflows.\n\n---\n\n## The Problem\n\nAI coding assistants are powerful but chaotic. Without constraints, they will:\n\n- Modify files they shouldn't touch\n- Refactor code nobody asked them to refactor\n- Make sweeping changes without documenting what they did\n- Break things in ways that are hard to trace back\n\nYou can't just *tell* an AI to behave. Instructions get ignored, forgotten, or misinterpreted. The only reliable way to constrain AI behavior is with **hard enforcement**: automated checks that block bad changes before they ship.\n\n## The Solution\n\nVibeScript creates a governance layer that:\n\n1. **Defines ownership** - Which files can AI modify freely? Which require human approval? Which are off-limits?\n\n2. **Requires declarations** - Before AI touches code, it must declare what it plans to modify and why\n\n3. **Enforces compliance** - Automated checks in CI that block PRs if the AI violated the rules\n\n4. **Creates audit trails** - Change manifests document what was done and how to undo it\n\n**The key insight**: You don't convince an AI to follow rules. You trap it in a workflow where the only way forward is to pass the gates.\n\n## How It Works\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│  AI writes code in .vibe.ts files with required directives  │\n│                            ↓                                │\n│  vibe:check validates directives and file permissions       │\n│                            ↓                                │\n│  vibe:guard validates ownership rules and manifests         │\n│                            ↓                                │\n│  CI blocks merge if any check fails                         │\n│                            ↓                                │\n│  Code ships only when compliant                             │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## Quick Start\n\n**Step 1**: Install VibeScript in your project\n\n```bash\npnpm add -D @ddnet-repo/vibescript\npnpm vibescript init\n```\n\n**Step 2**: Tell your AI to read the rules\n\nWhen starting a coding session with Claude Code or similar, say:\n\n> \"Before making any changes, read `.vibe/claude.instructions.md` and `.vibe/spec.md`. Follow the VibeScript governance rules. Run `pnpm vibe:check` before committing.\"\n\n**Step 3**: Enable branch protection in GitHub\n\nGo to Settings → Branches → Add rule for `main`:\n- Require status checks to pass\n- Select \"Vibe Check\" as required\n\nNow the AI physically cannot merge code that violates the rules.\n\n## What Gets Created\n\nAfter running `vibescript init`:\n\n```\n.vibe/\n  spec.md                 # The rules (AI reads this)\n  claude.instructions.md  # Operating manual for Claude\n  ownership.json          # Which files AI can touch\n  templates/              # File templates\n  reports/                # Violation reports\n  changes/                # Change manifests\n\n.github/workflows/\n  vibe.yml                # CI enforcement\n```\n\n## File Ownership Model\n\n| Extension | Who Owns It | AI Rights |\n|-----------|-------------|-----------|\n| `*.vibe.ts` | AI-owned | Freely create, modify, delete |\n| `*.human.ts` | Human-owned | Cannot modify without explicit permission |\n| `*.lock.ts` | Contract files | Must include test changes |\n| `*.ts` | Unowned | Not governed (gradual adoption) |\n\n**You choose what to govern.** Existing code isn't affected until you opt in by renaming files or configuring ownership globs.\n\n## The Directive System\n\nEvery `.vibe.ts` file must declare its intent:\n\n```typescript\n// @vibe:goal What this code accomplishes\n// @vibe:touch src/auth/**/*.ts, src/types/user.ts\n// @vibe:inputs What data/context is needed\n// @vibe:outputs What this produces\n// @vibe:constraints Limitations and requirements\n// @vibe:tests How to verify correctness\n// @vibe:risk low|medium|high\n// @vibe:rollback How to undo changes\n\nexport function myFeature() {\n  // Implementation\n}\n```\n\nThe `@vibe:touch` directive is critical: it declares which files the AI is *allowed* to modify. If the AI touches files not in this list, the check fails.\n\n## Enforcement Layers\n\n| Layer | When | What It Catches |\n|-------|------|-----------------|\n| Pre-commit hook | Before commit | Immediate local feedback |\n| GitHub Action | On PR | Blocks merge until fixed |\n| Branch protection | On merge | Final gate, no bypass |\n\nAll three layers run `pnpm vibe:check`, which:\n1. Validates ownership rules (vibe-guard)\n2. Validates directives and touch coverage (vibe-checker)\n\n## CLI Commands\n\n```bash\nvibescript init          # Set up governance in your project\nvibescript task \"desc\"   # Create a new .vibe.ts file with directives\nvibescript manifest \"x\"  # Create a change manifest\nvibescript doctor        # Diagnose configuration issues\nvibescript check         # Run all compliance checks\n```\n\n## Documentation\n\n- [Quickstart Guide](docs/quickstart.md) - Get running in 5 minutes\n- [CI/CD Setup](docs/ci-setup.md) - GitHub Actions and branch protection\n- [Authoring Vibe Files](docs/authoring-vibe-files.md) - Writing good directives\n- [Migration Guide](docs/making-existing-projects-compliant.md) - Adding to existing projects\n- [Common Failures](docs/common-failures.md) - Troubleshooting\n\n## Why \"VibeScript\"?\n\nBecause \"vibe-based coding\" is what happens when AI runs unsupervised. This is the antidote: explicit declarations, hard enforcement, and audit trails.\n\nThe vibes are nice. The scripts make sure nobody gets hurt.\n\n## License\n\nMIT\n\n## Author\n\nburtbyproxy <steve@datadigital.net>\n","readmeFilename":"README.md","_rev":"1-1cc49b5f6d8410b9fdb8eeec0a13c3de"}