ai-vibes 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ai-vibes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,345 @@
+# ai-vibes
+
+> A tiny CLI that scaffolds AI steering rules for your codebase.
+
+**The problem:** Your AI assistant writes amazing code... that looks nothing like the rest of your codebase. 🤦
+
+**The solution:** Give your AI the vibe check it deserves. Define your team's standards once, and let every AI assistant follow them.
+
+Think of it as `.editorconfig` but for AI behavior. Or a style guide that AIs actually read.
+
+## Install
+
+```bash
+# No installation needed - use npx
+npx ai-vibes init
+
+# Or install globally
+npm install -g ai-vibes
+```
+
+**Requirements:** Node.js 18+
+
+## Usage
+
+```bash
+# Interactive mode - prompts you for directory and manifest names
+npx ai-vibes init
+
+# Or skip the prompts with flags
+npx ai-vibes init --dir vibes --manifest vibes.yaml
+
+# Minimal mode - 3 essential files (recommended)
+npx ai-vibes init --minimal
+
+# Overwrite existing files
+npx ai-vibes init --force
+```
+
+This creates:
+
+- `vibes.yaml` - Manifest file
+- `vibes/` - Directory with rule documents
+
+## What You Get
+
+### Minimal Mode (3 files)
+
+- `security.md` - Never commit secrets, validate inputs
+- `unit-tests.md` - Test behavior, cover edge cases
+- `naming.md` - Consistent naming conventions
+
+### Full Mode (11 files)
+
+Everything in minimal, plus:
+
+- `architecture.md` - Follow existing patterns
+- `performance.md` - Optimization guidelines
+- `code-review.md` - Review standards
+- `error-handling.md` - Error patterns
+- `documentation.md` - Doc standards
+- `accessibility.md` - a11y guidelines
+- `api-design.md` - RESTful conventions
+- `git-workflow.md` - Commit standards
+
+## Daily Usage
+
+### Working with AI Assistants
+
+Once set up, reference your guidelines when using AI tools:
+
+**GitHub Copilot:**
+
+```
+@workspace Follow the guidelines in vibes.yaml
+```
+
+**Cursor:**
+
+```
+Create an API endpoint following the guidelines in vibes.yaml
+```
+
+**Claude/ChatGPT:**
+
+```bash
+cat vibes.yaml vibes/*.md
+# Paste into your conversation
+```
+
+### Updating Guidelines
+
+```bash
+# Edit a rule
+vim vibes/security.md
+
+# Commit changes
+git add vibes/
+git commit -m "docs: update security guidelines for API keys"
+```
+
+## CLI Options
+
+```
+npx ai-vibes init [options]
+
+Options:
+  --minimal              3 essential files instead of 11
+  --force                Overwrite existing files
+  --dir <name>           Directory name (interactive prompt if not provided)
+  --manifest <filename>  Manifest filename (interactive prompt if not provided)
+  -h, --help             Display help
+```
+
+**Interactive Mode:** If you don't provide `--dir` or `--manifest`, you'll be prompted:
+
+```
+Directory name for rule documents (default: vibes):
+Manifest filename (default: vibes.yaml):
+```
+
+## What It Does
+
+✅ Creates `vibes.yaml` manifest  
+✅ Creates rule documents in Markdown  
+✅ Provides starter templates  
+✅ Gives you a place to say "No, AI, we don't do that here"
+
+## What It Doesn't Do
+
+❌ Does not validate rules (it's not a linter, calm down)  
+❌ Does not enforce rules (you still need code review)  
+❌ Does not integrate with AI tools directly (BYOAI - Bring Your Own AI)  
+❌ Does not make coffee ☕
+
+ai-vibes is intentionally minimal - it scaffolds the structure, you customize the content. Think of it as the starter pack for your AI's training montage.
+
+## How It Works
+
+```mermaid
+graph TD
+    A[🚀 Run: npx ai-vibes init] --> B[📄 Creates vibes.yaml manifest]
+    B --> C[📁 Creates vibes/ directory with rule files]
+    C --> D[✏️ You customize the markdown files]
+    D --> E[🤖 Share with AI assistants]
+    E --> F[✨ AI follows your team's standards]
+
+    style A fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style B fill:#2196F3,stroke:#1565C0,color:#fff
+    style C fill:#2196F3,stroke:#1565C0,color:#fff
+    style D fill:#FF9800,stroke:#E65100,color:#fff
+    style E fill:#9C27B0,stroke:#6A1B9A,color:#fff
+    style F fill:#4CAF50,stroke:#2E7D32,color:#fff
+```
+
+**The magic:** The manifest (`vibes.yaml`) acts as a single source of truth that AI tools can read to discover all your coding standards in one place.
+
+## Setup Guide
+
+### Step-by-Step Setup
+
+**1. Navigate to your project**
+
+```bash
+cd /path/to/your-project
+```
+
+**2. Run ai-vibes**
+
+```bash
+npx ai-vibes init
+```
+
+**3. Answer the prompts** (or press Enter for defaults)
+
+```
+Directory name for rule documents (default: vibes):
+Manifest filename (default: vibes.yaml):
+```
+
+**4. Choose your mode**
+
+- Want all 11 templates? Just press Enter
+- Want minimal (3 files)? Run with `--minimal` flag
+
+**5. Verify the files were created**
+
+```bash
+ls vibes/           # Shows your rule files
+cat vibes.yaml      # Shows your manifest
+```
+
+**6. Customize for your team**
+
+Edit the generated files to match your standards:
+
+```bash
+# Add your security requirements
+vim vibes/security.md
+
+# Define your naming conventions
+vim vibes/naming.md
+
+# Set testing expectations
+vim vibes/unit-tests.md
+```
+
+**7. Commit to version control**
+
+```bash
+git add vibes.yaml vibes/
+git commit -m "docs: add AI coding guidelines"
+git push
+```
+
+**8. Share with your AI assistant**
+
+Now whenever you use an AI tool, reference your guidelines:
+
+```
+@workspace Follow the guidelines in vibes.yaml
+```
+
+**9. Keep it updated**
+
+As your team's practices evolve, update the markdown files:
+
+```bash
+vim vibes/security.md    # Add new security pattern
+git commit -am "docs: add OAuth2 security requirements"
+```
+
+### What Gets Created
+
+**Minimal Mode** (`--minimal`):
+
+```
+your-project/
+├── vibes.yaml          # Manifest with 3 rules
+└── vibes/
+    ├── security.md     # Security guidelines
+    ├── unit-tests.md   # Testing standards
+    └── naming.md       # Naming conventions
+```
+
+**Full Mode** (default):
+
+```
+your-project/
+├── vibes.yaml              # Manifest with 11 rules
+└── vibes/
+    ├── security.md         # Security guidelines
+    ├── unit-tests.md       # Testing standards
+    ├── naming.md           # Naming conventions
+    ├── architecture.md     # Architecture patterns
+    ├── performance.md      # Performance guidelines
+    ├── code-review.md      # Review standards
+    ├── error-handling.md   # Error patterns
+    ├── documentation.md    # Documentation standards
+    ├── accessibility.md    # Accessibility guidelines
+    ├── api-design.md       # API conventions
+    └── git-workflow.md     # Git standards
+```
+
+### Automation
+
+Skip the prompts for CI/CD or scripts:
+
+```bash
+npx ai-vibes init --dir .github/ai-rules --manifest ai-rules.yaml --minimal --force
+```
+
+## Manifest Format
+
+`vibes.yaml` maps rule IDs to file paths:
+
+```yaml
+version: 1
+
+rules:
+  security: "vibes/security.md"
+  unit-tests: "vibes/unit-tests.md"
+  naming: "vibes/naming.md"
+
+order:
+  - security
+  - unit-tests
+  - naming
+
+modes:
+  codegen:
+    include: [security, unit-tests, naming]
+  review:
+    include: [security, naming]
+```
+
+## Examples
+
+### Basic Setup
+
+```bash
+npx ai-vibes init --minimal
+```
+
+### Monorepo
+
+```bash
+cd packages/api
+npx ai-vibes init --dir ../../.ai-rules --manifest ../../ai-rules.yaml
+```
+
+### Custom Location
+
+```bash
+npx ai-vibes init --dir .github/ai-guidelines
+```
+
+## FAQ
+
+**Do I need to install this?**  
+No, use `npx ai-vibes init`. One command, zero commitment. Like a coding one-night stand, but productive.
+
+**Can I customize the templates?**  
+Yes! That's literally the entire point. These are starting points, not commandments carved in stone.
+
+**Can I add more rules?**  
+Absolutely. Got opinions about how semicolons should be used? Write a rule. Passionate about proper emoji usage in commit messages? Add it to the manifest.
+
+**Should I commit these files?**  
+Yes! Version control means time travel, and future-you will thank past-you for documenting these decisions.
+
+**Does this work with [my AI tool]?**  
+If your AI can read Markdown (spoiler: they all can), then yes. We're tool-agnostic. Bring your favorite AI, we'll provide the guidelines.
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT
+
+---
+
+**Repository:** https://github.com/HelpBits/ai-vibes  
+**Version:** 1.0.0

package/dist/cli.js

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/init.ts
+import { writeFile, mkdir, access } from "fs/promises";
+import { join } from "path";
+import { createInterface } from "readline";
+
+// src/templates.ts
+var security_md = '# Security\n\n## Purpose\n\nDefine security expectations for AI-generated code in this repo.\n\n## Do\n\n- **Never commit secrets** \u2013 no API keys, tokens, passwords in code or logs\n- **Validate all inputs** \u2013 especially user-provided data, query params, form fields\n- **Use environment variables** for secrets (e.g., `.env` files, not committed)\n- **Sanitize outputs** \u2013 prevent XSS, SQL injection, command injection\n- **Follow least privilege** \u2013 grant minimal necessary permissions\n- **Keep dependencies updated** \u2013 regularly audit and update packages\n- **Use secure defaults** \u2013 HTTPS, secure cookies, strong crypto\n- **Log security events** \u2013 failed auth attempts, suspicious activity (without logging sensitive data)\n\n## Don\'t\n\n- **Don\'t hardcode credentials** \u2013 ever\n- **Don\'t trust user input** \u2013 always validate and sanitize\n- **Don\'t use weak crypto** \u2013 no MD5, SHA1 for passwords; use bcrypt, argon2, or scrypt\n- **Don\'t expose stack traces** \u2013 in production error messages\n- **Don\'t add risky dependencies casually** \u2013 vet packages before installing\n- **Don\'t skip security headers** \u2013 CSP, HSTS, X-Frame-Options, etc.\n\n## Examples\n\n### \u2705 Good: Environment variables\n\n```javascript\nconst apiKey = process.env.API_KEY;\nif (!apiKey) {\n  throw new Error("API_KEY not configured");\n}\n```\n\n### \u274C Bad: Hardcoded secret\n\n```javascript\nconst apiKey = "sk-1234567890abcdef"; // NEVER do this\n```\n\n### \u2705 Good: Input validation\n\n```javascript\nfunction getUser(userId) {\n  if (!/^[0-9]+$/.test(userId)) {\n    throw new Error("Invalid user ID");\n  }\n  return db.query("SELECT * FROM users WHERE id = ?", [userId]);\n}\n```\n\n### \u274C Bad: SQL injection risk\n\n```javascript\nfunction getUser(userId) {\n  return db.query(`SELECT * FROM users WHERE id = ${userId}`); // vulnerable\n}\n```\n';
+var unit_tests_md = '# Unit Tests\n\n## Purpose\n\nDefine how AI should write and maintain unit tests in this repo.\n\n## Do\n\n- **Update tests when behavior changes** \u2013 tests should reflect current expected behavior\n- **Cover edge cases** \u2013 empty inputs, null, undefined, boundary values\n- **Test error paths** \u2013 not just happy paths\n- **Use descriptive test names** \u2013 `it(\'should return 404 when user not found\')`\n- **Keep tests fast** \u2013 mock external dependencies (APIs, databases)\n- **Test one thing per test** \u2013 focused assertions\n- **Use test fixtures** \u2013 reusable test data\n- **Assert meaningful outputs** \u2013 not just "doesn\'t crash"\n\n## Don\'t\n\n- **Don\'t test implementation details** \u2013 test behavior, not private methods\n- **Don\'t write flaky tests** \u2013 avoid timeouts, race conditions\n- **Don\'t skip failing tests** \u2013 fix or remove them\n- **Don\'t copy-paste tests** \u2013 extract shared setup\n- **Don\'t mock everything** \u2013 test real logic when possible\n- **Don\'t ignore test failures** \u2013 they indicate real issues\n\n## Examples\n\n### \u2705 Good: Behavior-focused test\n\n```javascript\ndescribe("UserService", () => {\n  it("should throw error when creating user with duplicate email", async () => {\n    await createUser({ email: "test@example.com" });\n\n    await expect(createUser({ email: "test@example.com" })).rejects.toThrow(\n      "Email already exists",\n    );\n  });\n});\n```\n\n### \u2705 Good: Edge case coverage\n\n```javascript\ndescribe("calculateDiscount", () => {\n  it("should return 0 for negative prices", () => {\n    expect(calculateDiscount(-10)).toBe(0);\n  });\n\n  it("should return 0 for null price", () => {\n    expect(calculateDiscount(null)).toBe(0);\n  });\n\n  it("should handle zero price", () => {\n    expect(calculateDiscount(0)).toBe(0);\n  });\n});\n```\n\n### \u274C Bad: Testing implementation details\n\n```javascript\nit("should call internal _parseData method", () => {\n  const spy = jest.spyOn(service, "_parseData");\n  service.process(data);\n  expect(spy).toHaveBeenCalled(); // testing internals, not behavior\n});\n```\n';
+var naming_md = '# Naming Conventions\n\n## Purpose\n\nDefine naming standards for consistency across the codebase.\n\n## Do\n\n- **Use descriptive names** \u2013 `getUserById` not `get`\n- **Follow language conventions** \u2013 camelCase for JS/TS, snake_case for Python\n- **Be consistent** \u2013 if the repo uses `fetch*`, don\'t add `get*` functions\n- **Use plural for collections** \u2013 `users`, `items`\n- **Use verb-noun for functions** \u2013 `createUser`, `deletePost`\n- **Use clear boolean names** \u2013 `isActive`, `hasPermission`, `canEdit`\n- **Avoid abbreviations** \u2013 unless widely known (HTTP, API, ID)\n- **Match domain language** \u2013 use terms from the product/business\n\n## Don\'t\n\n- **Don\'t be cryptic** \u2013 `a`, `tmp`, `data2`\n- **Don\'t use misleading names** \u2013 `get*` should not modify state\n- **Don\'t mix conventions** \u2013 pick one and stick with it\n- **Don\'t use generic names** \u2013 `handler`, `manager`, `helper` without context\n- **Don\'t overuse prefixes** \u2013 `myFunction`, `theVariable`\n\n## Examples\n\n### \u2705 Good: Clear function names\n\n```javascript\nfunction createUser(userData) {}\nfunction deletePost(postId) {}\nfunction isAuthenticated(user) {}\n```\n\n### \u274C Bad: Vague names\n\n```javascript\nfunction process(d) {} // what does this do?\nfunction handle() {} // handle what?\nfunction doStuff() {} // too generic\n```\n\n### \u2705 Good: Descriptive variables\n\n```javascript\nconst activeUsers = users.filter((u) => u.isActive);\nconst maxRetries = 3;\nconst apiBaseUrl = "https://api.example.com";\n```\n\n### \u274C Bad: Unclear variables\n\n```javascript\nconst arr = users.filter((u) => u.isActive); // what kind of array?\nconst num = 3; // what number?\nconst url = "https://api.example.com"; // which URL?\n```\n\n### \u2705 Good: Boolean naming\n\n```javascript\nconst isLoading = true;\nconst hasPermission = user.role === "admin";\nconst canDelete = isOwner || isAdmin;\n```\n\n### \u274C Bad: Unclear booleans\n\n```javascript\nconst loading = true;      // could be a loading indicator element\nconst permission = true;   // which permission?\nconst delete = true;       // "delete" is ambiguous\n```\n';
+var architecture_md = "# Architecture\n\n## Purpose\n\nDefine architectural patterns and organization principles for this repo.\n\n## Do\n\n- **Follow existing patterns** \u2013 if the repo has a structure, maintain it\n- **Put code in the right place** \u2013 controllers, services, models, utils\n- **Reuse existing utilities** \u2013 check before creating new helper functions\n- **Keep modules focused** \u2013 single responsibility principle\n- **Minimize dependencies** \u2013 between modules\n- **Document architecture decisions** \u2013 why, not just what\n- **Use dependency injection** \u2013 for testability\n- **Separate concerns** \u2013 business logic, data access, presentation\n\n## Don't\n\n- **Don't create new patterns** \u2013 without justification or discussion\n- **Don't duplicate functionality** \u2013 search for existing solutions first\n- **Don't tightly couple modules** \u2013 avoid circular dependencies\n- **Don't mix layers** \u2013 keep business logic out of controllers\n- **Don't bypass abstractions** \u2013 use the data layer, don't query directly\n- **Don't ignore folder structure** \u2013 respect the repo's organization\n\n## Examples\n\n### \u2705 Good: Layered architecture\n\n```javascript\n// controller/userController.js\nexport async function getUser(req, res) {\n  const user = await userService.findById(req.params.id);\n  res.json(user);\n}\n\n// service/userService.js\nexport async function findById(id) {\n  return userRepository.findById(id);\n}\n\n// repository/userRepository.js\nexport async function findById(id) {\n  return db.query(\"SELECT * FROM users WHERE id = ?\", [id]);\n}\n```\n\n### \u274C Bad: Mixed concerns\n\n```javascript\n// controller/userController.js\nexport async function getUser(req, res) {\n  // Don't put database queries directly in controllers\n  const user = await db.query(\"SELECT * FROM users WHERE id = ?\", [\n    req.params.id,\n  ]);\n  res.json(user);\n}\n```\n\n### \u2705 Good: Reusing utilities\n\n```javascript\nimport { formatDate } from \"../utils/date\";\nimport { validateEmail } from \"../utils/validation\";\n\nconst formattedDate = formatDate(user.createdAt);\n```\n\n### \u274C Bad: Duplicating utilities\n\n```javascript\n// Creating new date formatting when one exists\nfunction myDateFormatter(date) {\n  // duplicates existing formatDate utility\n}\n```\n";
+var performance_md = "# Performance\n\n## Purpose\n\nDefine performance expectations and optimization guidelines for AI-generated code.\n\n## Do\n\n- **Measure before optimizing** \u2013 use profilers and benchmarks\n- **Use appropriate data structures** \u2013 Map for lookups, Set for uniqueness, Array for ordered data\n- **Cache expensive operations** \u2013 memoize, cache API calls, precompute when possible\n- **Avoid unnecessary re-renders** \u2013 React.memo, useMemo, useCallback where appropriate\n- **Lazy load when possible** \u2013 code splitting, dynamic imports, lazy components\n- **Optimize loops** \u2013 avoid nested loops with large datasets, use early returns\n- **Use efficient algorithms** \u2013 consider Big O complexity\n- **Debounce/throttle** \u2013 for frequent events (scroll, resize, input)\n- **Optimize images** \u2013 compress, use appropriate formats, lazy load\n- **Monitor bundle size** \u2013 keep dependencies lean\n\n## Don't\n\n- **Don't premature optimize** \u2013 optimize hot paths only after measuring\n- **Don't block the main thread** \u2013 use Web Workers for heavy computation\n- **Don't fetch in loops** \u2013 batch API calls, use Promise.all\n- **Don't ignore memory leaks** \u2013 clean up event listeners, timers, subscriptions\n- **Don't load everything upfront** \u2013 use pagination, infinite scroll, virtualization\n- **Don't ignore Core Web Vitals** \u2013 LCP, FID, CLS matter for UX\n\n## Examples\n\n### \u2705 Good: Memoization\n\n```javascript\nconst cache = new Map();\n\nfunction expensiveOperation(key) {\n  if (cache.has(key)) return cache.get(key);\n\n  const result = /* expensive computation */;\n  cache.set(key, result);\n  return result;\n}\n```\n\n### \u274C Bad: Repeated computation\n\n```javascript\nfunction expensiveOperation(key) {\n  return /* expensive computation every time */;\n}\n```\n\n### \u2705 Good: Batch API calls\n\n```javascript\nconst userIds = [1, 2, 3, 4, 5];\nconst users = await fetchUsers(userIds); // Single request\n```\n\n### \u274C Bad: N+1 queries\n\n```javascript\nconst users = [];\nfor (const id of userIds) {\n  users.push(await fetchUser(id)); // 5 separate requests!\n}\n```\n";
+var code_review_md = "# Code Review\n\n## Purpose\n\nDefine standards for code reviews and what to look for when reviewing AI-generated code.\n\n## Do\n\n- **Check for security issues** \u2013 SQL injection, XSS, hardcoded secrets\n- **Verify error handling** \u2013 proper try/catch, error messages, fallbacks\n- **Review test coverage** \u2013 edge cases covered, meaningful assertions\n- **Check naming consistency** \u2013 follows repo conventions\n- **Verify documentation** \u2013 complex logic explained, JSDoc/comments where needed\n- **Look for duplication** \u2013 reusable code extracted to functions/modules\n- **Check dependencies** \u2013 necessary, up-to-date, no suspicious packages\n- **Verify accessibility** \u2013 semantic HTML, ARIA labels, keyboard navigation\n- **Check performance** \u2013 no obvious bottlenecks, efficient algorithms\n- **Review git history** \u2013 clear commit messages, logical commits\n\n## Don't\n\n- **Don't approve blindly** \u2013 actually read and understand the changes\n- **Don't nitpick style** \u2013 let linters/formatters handle it\n- **Don't block on preferences** \u2013 focus on correctness and maintainability\n- **Don't merge with unresolved comments** \u2013 address or explicitly defer\n- **Don't skip testing** \u2013 actually run the code locally\n- **Don't assume AI is always right** \u2013 LLMs make mistakes\n\n## Examples\n\n### \u2705 Good: Constructive feedback\n\n```\nThis function could throw if userId is undefined.\nConsider adding validation:\n  if (!userId) throw new Error('userId required');\n```\n\n### \u274C Bad: Vague criticism\n\n```\nThis doesn't look right\n```\n\n### \u2705 Good: Security catch\n\n```\n\u26A0\uFE0F SQL injection risk here - use parameterized queries:\n  db.query('SELECT * FROM users WHERE id = ?', [userId])\n```\n";
+var error_handling_md = "# Error Handling\n\n## Purpose\n\nDefine how errors should be handled and reported in AI-generated code.\n\n## Do\n\n- **Use try/catch for async operations** \u2013 especially API calls, file I/O\n- **Throw meaningful errors** \u2013 descriptive messages, include context\n- **Use custom error classes** \u2013 for domain-specific errors\n- **Log errors properly** \u2013 include stack traces, context, but not secrets\n- **Handle errors at appropriate level** \u2013 don't catch too early\n- **Provide fallbacks** \u2013 graceful degradation when possible\n- **Validate inputs early** \u2013 fail fast with clear errors\n- **Use error boundaries** \u2013 in React/UI frameworks\n- **Return error objects** \u2013 instead of throwing in some cases (Result pattern)\n- **Document error cases** \u2013 what exceptions can be thrown\n\n## Don't\n\n- **Don't swallow errors** \u2013 empty catch blocks hide bugs\n- **Don't expose internals** \u2013 no stack traces in production to users\n- **Don't use errors for control flow** \u2013 errors are for exceptional cases\n- **Don't log secrets** \u2013 no passwords, tokens, PII in error logs\n- **Don't ignore promise rejections** \u2013 always handle with .catch or try/catch\n- **Don't use generic messages** \u2013 \"Something went wrong\" isn't helpful\n\n## Examples\n\n### \u2705 Good: Specific error with context\n\n```javascript\nasync function getUser(userId) {\n  if (!userId) {\n    throw new Error(\"userId is required\");\n  }\n\n  try {\n    return await api.fetchUser(userId);\n  } catch (error) {\n    throw new Error(`Failed to fetch user ${userId}: ${error.message}`);\n  }\n}\n```\n\n### \u274C Bad: Swallowed error\n\n```javascript\nasync function getUser(userId) {\n  try {\n    return await api.fetchUser(userId);\n  } catch (error) {\n    // Silent failure - bug is hidden!\n  }\n}\n```\n\n### \u2705 Good: Error boundary (React)\n\n```javascript\nclass ErrorBoundary extends React.Component {\n  state = { hasError: false };\n\n  static getDerivedStateFromError(error) {\n    return { hasError: true };\n  }\n\n  componentDidCatch(error, info) {\n    logError(error, info);\n  }\n\n  render() {\n    if (this.state.hasError) {\n      return <ErrorFallback />;\n    }\n    return this.props.children;\n  }\n}\n```\n";
+var documentation_md = "# Documentation\n\n## Purpose\n\nDefine documentation standards for AI-generated code.\n\n## Do\n\n- **Document the \"why\" not the \"what\"** \u2013 code shows what, comments explain why\n- **Add JSDoc for public APIs** \u2013 parameters, return types, examples\n- **Document complex logic** \u2013 algorithms, business rules, non-obvious code\n- **Keep README updated** \u2013 installation, usage, examples\n- **Add inline comments** \u2013 for tricky parts, workarounds, TODOs\n- **Document breaking changes** \u2013 in CHANGELOG or commit messages\n- **Include examples** \u2013 especially for libraries and utilities\n- **Document edge cases** \u2013 what assumptions are made\n- **Link to related docs** \u2013 design docs, tickets, RFCs\n- **Keep docs close to code** \u2013 avoid docs getting stale\n\n## Don't\n\n- **Don't state the obvious** \u2013 `// increment i` is useless\n- **Don't let docs drift** \u2013 update docs when code changes\n- **Don't over-document** \u2013 clear code needs fewer comments\n- **Don't write novels** \u2013 be concise and clear\n- **Don't document implementation details** \u2013 unless necessary\n- **Don't use outdated examples** \u2013 test your examples\n\n## Examples\n\n### \u2705 Good: Explains \"why\"\n\n```javascript\n// Using setTimeout instead of setInterval because the API call\n// can take longer than 5s, which would cause requests to queue up\nsetTimeout(() => pollAPI(), 5000);\n```\n\n### \u274C Bad: States the obvious\n\n```javascript\n// Call the API\ncallAPI();\n```\n\n### \u2705 Good: JSDoc with examples\n\n```javascript\n/**\n * Formats a date for display in the UI\n * @param {Date} date - The date to format\n * @param {string} locale - The locale (e.g., 'en-US', 'es-ES')\n * @returns {string} Formatted date string\n * @example\n *   formatDate(new Date(), 'en-US') // \"Jan 1, 2024\"\n */\nfunction formatDate(date, locale) {\n  return new Intl.DateTimeFormat(locale).format(date);\n}\n```\n\n### \u2705 Good: Complex logic explanation\n\n```javascript\n// We're using a binary search here because the data is sorted\n// and can be very large (100k+ items). Linear search would be O(n).\n// This gives us O(log n) performance.\nfunction binarySearch(arr, target) {\n  // ...\n}\n```\n";
+var accessibility_md = '# Accessibility (a11y)\n\n## Purpose\n\nDefine accessibility standards for AI-generated UI code to ensure inclusivity.\n\n## Do\n\n- **Use semantic HTML** \u2013 `<button>`, `<nav>`, `<main>`, not just `<div>`\n- **Add ARIA labels** \u2013 when semantic HTML isn\'t enough\n- **Ensure keyboard navigation** \u2013 tab order, focus management, shortcuts\n- **Provide alt text** \u2013 for all images (empty alt="" for decorative)\n- **Use sufficient color contrast** \u2013 WCAG AA minimum (4.5:1 for text)\n- **Make clickable areas large** \u2013 44x44px minimum touch targets\n- **Support screen readers** \u2013 test with VoiceOver, NVDA, JAWS\n- **Add skip links** \u2013 "Skip to main content" for keyboard users\n- **Use labels for inputs** \u2013 properly associated with `for`/`id`\n- **Test with keyboard only** \u2013 tab, enter, escape, arrows\n\n## Don\'t\n\n- **Don\'t rely on color alone** \u2013 use icons, text, patterns too\n- **Don\'t use `<div>` for buttons** \u2013 use `<button>` or proper ARIA\n- **Don\'t auto-play media** \u2013 provide controls, respect prefers-reduced-motion\n- **Don\'t break zoom** \u2013 avoid `maximum-scale=1` in viewport\n- **Don\'t use placeholder as label** \u2013 placeholders disappear on input\n- **Don\'t forget focus styles** \u2013 never `outline: none` without alternative\n- **Don\'t hide content** \u2013 that should be available to screen readers\n\n## Examples\n\n### \u2705 Good: Semantic HTML\n\n```jsx\n<button onClick={handleClick}>Delete</button>\n```\n\n### \u274C Bad: Div as button\n\n```jsx\n<div onClick={handleClick}>Delete</div>\n```\n\n### \u2705 Good: Proper label\n\n```jsx\n<label htmlFor="email">Email</label>\n<input id="email" type="email" />\n```\n\n### \u274C Bad: Placeholder as label\n\n```jsx\n<input type="email" placeholder="Email" />\n```\n\n### \u2705 Good: Icon with label\n\n```jsx\n<button aria-label="Close dialog">\n  <XIcon />\n</button>\n```\n\n### \u2705 Good: Keyboard support\n\n```javascript\nfunction handleKeyDown(e) {\n  if (e.key === "Escape") {\n    closeModal();\n  }\n  if (e.key === "Enter" || e.key === " ") {\n    handleAction();\n  }\n}\n```\n';
+var api_design_md = '# API Design\n\n## Purpose\n\nDefine standards for designing APIs (REST, GraphQL, internal modules).\n\n## Do\n\n- **Use RESTful conventions** \u2013 GET (read), POST (create), PUT/PATCH (update), DELETE\n- **Version your API** \u2013 /v1/, /v2/, or header-based versioning\n- **Use plural nouns** \u2013 `/users`, `/posts`, not `/user`, `/post`\n- **Return proper HTTP status codes** \u2013 200 success, 201 created, 400 bad request, 404 not found, 500 error\n- **Include pagination** \u2013 for list endpoints (limit, offset or cursor)\n- **Validate inputs** \u2013 return 400 with clear error messages\n- **Use consistent naming** \u2013 camelCase or snake_case, pick one\n- **Include timestamps** \u2013 createdAt, updatedAt for resources\n- **Document your API** \u2013 OpenAPI/Swagger specs\n- **Handle errors gracefully** \u2013 return error objects with code and message\n\n## Don\'t\n\n- **Don\'t use verbs in URLs** \u2013 use HTTP methods instead\n- **Don\'t expose internal IDs** \u2013 use UUIDs or opaque identifiers\n- **Don\'t return different structures** \u2013 for same endpoint in different states\n- **Don\'t forget rate limiting** \u2013 protect against abuse\n- **Don\'t expose stack traces** \u2013 in production error responses\n- **Don\'t break backward compatibility** \u2013 without versioning\n- **Don\'t use GET for mutations** \u2013 GET should be idempotent\n\n## Examples\n\n### \u2705 Good: RESTful design\n\n```\nGET    /v1/users          # List users\nGET    /v1/users/123      # Get user\nPOST   /v1/users          # Create user\nPATCH  /v1/users/123      # Update user\nDELETE /v1/users/123      # Delete user\n```\n\n### \u274C Bad: Non-RESTful\n\n```\nGET  /getUsers\nPOST /createUser\nPOST /deleteUser\n```\n\n### \u2705 Good: Error response\n\n```json\n{\n  "error": {\n    "code": "INVALID_EMAIL",\n    "message": "Email address is not valid",\n    "field": "email"\n  }\n}\n```\n\n### \u274C Bad: Vague error\n\n```json\n{\n  "error": "Bad request"\n}\n```\n\n### \u2705 Good: Pagination\n\n```json\n{\n  "data": [...],\n  "pagination": {\n    "total": 1000,\n    "page": 1,\n    "pageSize": 20,\n    "totalPages": 50\n  }\n}\n```\n';
+var git_workflow_md = "# Git Workflow\n\n## Purpose\n\nDefine Git commit and branch standards for AI-generated code changes.\n\n## Do\n\n- **Write clear commit messages** \u2013 use conventional commits format\n- **Make atomic commits** \u2013 one logical change per commit\n- **Use descriptive branch names** \u2013 feature/add-login, fix/memory-leak\n- **Keep commits small** \u2013 easier to review and revert\n- **Test before committing** \u2013 ensure code works\n- **Write commit body** \u2013 for complex changes, explain why\n- **Reference issues** \u2013 \"Fixes #123\" in commit message\n- **Squash before merge** \u2013 keep main branch clean (if team convention)\n- **Pull before push** \u2013 avoid merge conflicts\n- **Use feature branches** \u2013 never commit directly to main\n\n## Don't\n\n- **Don't commit secrets** \u2013 use .gitignore, check before push\n- **Don't commit commented code** \u2013 delete it, Git has history\n- **Don't commit build artifacts** \u2013 node_modules, dist/, .env\n- **Don't use vague messages** \u2013 \"fix bug\", \"update code\"\n- **Don't commit WIP** \u2013 to shared branches\n- **Don't rewrite public history** \u2013 no force push to main/shared branches\n- **Don't make giant commits** \u2013 breaks down to reviewable chunks\n\n## Examples\n\n### \u2705 Good: Conventional commit\n\n```\nfeat: add user authentication with JWT\n\nImplements login, logout, and token refresh endpoints.\nUses bcrypt for password hashing and validates tokens\non protected routes.\n\nFixes #45\n```\n\n### \u274C Bad: Vague message\n\n```\nupdated stuff\n```\n\n### \u2705 Good: Branch naming\n\n```\nfeature/user-authentication\nfix/login-button-spacing\nrefactor/api-client-structure\ndocs/update-readme\n```\n\n### \u274C Bad: Branch naming\n\n```\nmy-branch\ntest\nnew-stuff\n```\n\n### Conventional Commit Types\n\n- `feat:` New feature\n- `fix:` Bug fix\n- `docs:` Documentation\n- `style:` Formatting, no code change\n- `refactor:` Code restructuring\n- `test:` Adding tests\n- `chore:` Maintenance tasks\n- `perf:` Performance improvement\n\n```\n\n```\n";
+var TEMPLATES = {
+  "security.md": security_md,
+  "unit-tests.md": unit_tests_md,
+  "naming.md": naming_md,
+  "architecture.md": architecture_md,
+  "performance.md": performance_md,
+  "code-review.md": code_review_md,
+  "error-handling.md": error_handling_md,
+  "documentation.md": documentation_md,
+  "accessibility.md": accessibility_md,
+  "api-design.md": api_design_md,
+  "git-workflow.md": git_workflow_md
+};
+var RULE_DEFINITIONS = [
+  {
+    "id": "security",
+    "filename": "security.md",
+    "minimal": true,
+    "modes": [
+      "codegen",
+      "review",
+      "test",
+      "docs",
+      "ops"
+    ]
+  },
+  {
+    "id": "unit-tests",
+    "filename": "unit-tests.md",
+    "minimal": true,
+    "modes": [
+      "codegen",
+      "test"
+    ]
+  },
+  {
+    "id": "naming",
+    "filename": "naming.md",
+    "minimal": true,
+    "modes": [
+      "codegen",
+      "review"
+    ]
+  },
+  {
+    "id": "architecture",
+    "filename": "architecture.md",
+    "minimal": false,
+    "modes": [
+      "codegen",
+      "review",
+      "ops"
+    ]
+  },
+  {
+    "id": "performance",
+    "filename": "performance.md",
+    "minimal": false,
+    "modes": [
+      "codegen",
+      "review"
+    ]
+  },
+  {
+    "id": "code-review",
+    "filename": "code-review.md",
+    "minimal": false,
+    "modes": [
+      "review"
+    ]
+  },
+  {
+    "id": "error-handling",
+    "filename": "error-handling.md",
+    "minimal": false,
+    "modes": [
+      "codegen",
+      "review"
+    ]
+  },
+  {
+    "id": "documentation",
+    "filename": "documentation.md",
+    "minimal": false,
+    "modes": [
+      "codegen",
+      "docs"
+    ]
+  },
+  {
+    "id": "accessibility",
+    "filename": "accessibility.md",
+    "minimal": false,
+    "modes": [
+      "codegen",
+      "review"
+    ]
+  },
+  {
+    "id": "api-design",
+    "filename": "api-design.md",
+    "minimal": false,
+    "modes": [
+      "codegen",
+      "review",
+      "ops"
+    ]
+  },
+  {
+    "id": "git-workflow",
+    "filename": "git-workflow.md",
+    "minimal": false,
+    "modes": [
+      "docs",
+      "ops"
+    ]
+  }
+];
+function loadTemplate(filename) {
+  const template = TEMPLATES[filename];
+  if (!template) {
+    throw new Error(`Template not found: ${filename}`);
+  }
+  return template;
+}
+function generateManifest(options) {
+  const { dir, minimal } = options;
+  const activeRules = RULE_DEFINITIONS.filter(
+    (rule) => minimal ? rule.minimal : true
+  );
+  const rules = activeRules.map((rule) => `  ${rule.id}: "${dir}/${rule.filename}"`).join("\n");
+  const order = activeRules.map((rule) => `  - ${rule.id}`).join("\n");
+  const modeNames = ["codegen", "review", "test", "docs", "ops"];
+  const modesSection = modeNames.map((modeName) => {
+    const rulesForMode = activeRules.filter((rule) => rule.modes.includes(modeName)).map((rule) => rule.id);
+    return `  ${modeName}:
+    include: [${rulesForMode.join(", ")}]`;
+  }).join("\n");
+  return `version: 1
+
+about:
+  name: "Repo Vibes"
+  description: "How AIs should work in this repo"
+
+rules:
+${rules}
+
+order:
+${order}
+
+modes:
+${modesSection}
+`;
+}
+function getRuleTemplates(minimal) {
+  return RULE_DEFINITIONS.filter((rule) => minimal ? rule.minimal : true).map((rule) => ({
+    filename: rule.filename,
+    content: loadTemplate(rule.filename)
+  }));
+}
+
+// src/init.ts
+function prompt(question, defaultValue) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise((resolve) => {
+    rl.question(`${question} (default: ${defaultValue}): `, (answer) => {
+      rl.close();
+      resolve(answer.trim() || defaultValue);
+    });
+  });
+}
+function validateOptions(options) {
+  const { dir, manifest } = options;
+  if (!dir || dir.trim() === "") {
+    throw new Error("Directory name cannot be empty");
+  }
+  if (dir.includes("..") || dir.startsWith("/") || dir.startsWith("\\")) {
+    throw new Error("Directory name cannot contain path traversal patterns or be absolute");
+  }
+  const invalidDirChars = /[<>:"|?*\x00-\x1F]/;
+  if (invalidDirChars.test(dir)) {
+    throw new Error("Directory name contains invalid characters");
+  }
+  if (!manifest || manifest.trim() === "") {
+    throw new Error("Manifest filename cannot be empty");
+  }
+  if (!manifest.endsWith(".yaml") && !manifest.endsWith(".yml")) {
+    throw new Error("Manifest filename must end with .yaml or .yml");
+  }
+  if (manifest.includes("/") || manifest.includes("\\")) {
+    throw new Error("Manifest filename cannot contain path separators");
+  }
+  const invalidFileChars = /[<>:"|?*\x00-\x1F]/;
+  if (invalidFileChars.test(manifest)) {
+    throw new Error("Manifest filename contains invalid characters");
+  }
+}
+async function init(options) {
+  const { force, minimal } = options;
+  const dir = options.dir || await prompt("Directory name for rule documents", "vibes");
+  const manifest = options.manifest || await prompt("Manifest filename", "vibes.yaml");
+  validateOptions({ force, minimal, dir, manifest });
+  const cwd = process.cwd();
+  const results = [];
+  const manifestPath = join(cwd, manifest);
+  const manifestExists = await fileExists(manifestPath);
+  if (!manifestExists || force) {
+    try {
+      const manifestContent = generateManifest({ dir, minimal });
+      await writeFile(manifestPath, manifestContent, "utf-8");
+      results.push({
+        path: manifest,
+        status: manifestExists ? "overwritten" : "created"
+      });
+    } catch (error) {
+      throw new Error(`Failed to write manifest file: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+  } else {
+    results.push({
+      path: manifest,
+      status: "skipped"
+    });
+  }
+  try {
+    const rulesDir2 = join(cwd, dir);
+    await mkdir(rulesDir2, { recursive: true });
+  } catch (error) {
+    throw new Error(`Failed to create directory '${dir}': ${error instanceof Error ? error.message : "Unknown error"}`);
+  }
+  const rulesDir = join(cwd, dir);
+  const templates = getRuleTemplates(minimal);
+  for (const template of templates) {
+    const filePath = join(rulesDir, template.filename);
+    const fileAlreadyExists = await fileExists(filePath);
+    if (!fileAlreadyExists || force) {
+      try {
+        await writeFile(filePath, template.content, "utf-8");
+        results.push({
+          path: join(dir, template.filename),
+          status: fileAlreadyExists ? "overwritten" : "created"
+        });
+      } catch (error) {
+        throw new Error(`Failed to write rule file '${template.filename}': ${error instanceof Error ? error.message : "Unknown error"}`);
+      }
+    } else {
+      results.push({
+        path: join(dir, template.filename),
+        status: "skipped"
+      });
+    }
+  }
+  printSummary(results);
+  if (results.some((r) => r.status === "created" || r.status === "overwritten")) {
+    console.log("\nIf this saves your team time, consider sponsoring the project:");
+    console.log("https://github.com/sponsors/ai-vibes");
+  }
+}
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function printSummary(results) {
+  const created = results.filter((r) => r.status === "created");
+  const skipped = results.filter((r) => r.status === "skipped");
+  const overwritten = results.filter((r) => r.status === "overwritten");
+  if (created.length > 0) {
+    console.log("\n\u2713 Created:");
+    created.forEach((r) => console.log(`  - ${r.path}`));
+  }
+  if (overwritten.length > 0) {
+    console.log("\n\u2713 Overwritten:");
+    overwritten.forEach((r) => console.log(`  - ${r.path}`));
+  }
+  if (skipped.length > 0) {
+    console.log("\n\u25CB Skipped (already exists):");
+    skipped.forEach((r) => console.log(`  - ${r.path}`));
+  }
+}
+
+// src/cli.ts
+var program = new Command();
+program.name("ai-vibes").description("Initialize a standard, repo-local AI steering manifest and rule documents").version("1.0.0");
+program.command("init").description("Initialize vibes.yaml and starter rule documents").option("--force", "Overwrite existing files", false).option("--minimal", "Create minimal starter set (3 essential files: security, unit-tests, naming)", false).option("--dir <name>", "Directory name for rule documents").option("--manifest <filename>", "Manifest filename").action(async (options) => {
+  try {
+    await init({
+      force: options.force,
+      minimal: options.minimal,
+      dir: options.dir,
+      manifest: options.manifest
+    });
+  } catch (error) {
+    console.error("Error initializing ai-vibes:", error);
+    process.exit(1);
+  }
+});
+program.parse();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "ai-vibes",
+  "version": "1.0.0",
+  "description": "A tiny CLI that initializes a standard, repo-local AI steering manifest and rule documents",
+  "type": "module",
+  "main": "dist/cli.js",
+  "bin": {
+    "ai-vibes": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "generate": "node scripts/generate-templates.js",
+    "prebuild": "npm run generate",
+    "build": "tsup src/cli.ts --format esm --clean",
+    "dev": "tsup src/cli.ts --format esm --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "rules",
+    "guidelines",
+    "code-quality",
+    "conventions",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3"
+  }
+}