@vibedx/vibekit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 vibedx
+
+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,368 @@
+```
+╭─────────────────────────────────────────────────────────────────╮
+│                                                                 │
+│   ██╗   ██╗██╗██████╗ ███████╗    ██╗  ██╗██╗████████╗        │
+│   ██║   ██║██║██╔══██╗██╔════╝    ██║ ██╔╝██║╚══██╔══╝        │
+│   ██║   ██║██║██████╔╝█████╗      █████╔╝ ██║   ██║           │
+│   ╚██╗ ██╔╝██║██╔══██╗██╔══╝      ██╔═██╗ ██║   ██║           │
+│    ╚████╔╝ ██║██████╔╝███████╗    ██║  ██╗██║   ██║           │
+│     ╚═══╝  ╚═╝╚═════╝ ╚══════╝    ╚═╝  ╚═╝╚═╝   ╚═╝           │
+│                                                                 │
+╰─────────────────────────────────────────────────────────────────╯
+```
+
+<div align="center">
+
+[![npm version](https://img.shields.io/npm/v/@vibedx/vibekit.svg)](https://www.npmjs.com/package/@vibedx/vibekit)
+[![npm downloads](https://img.shields.io/npm/dm/@vibedx/vibekit.svg)](https://www.npmjs.com/package/@vibedx/vibekit)
+[![GitHub license](https://img.shields.io/github/license/vibedx/vibekit.svg)](https://github.com/vibedx/vibekit/blob/main/LICENSE)
+
+**A CLI tool to help you vibe your code better** ✨  
+*Vibe your development workflow*  
+_vibekit uses vibekit to develop vibekit - we vibin!_ 🔄
+
+</div>
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# Install globally
+npm install -g @vibedx/vibekit
+
+# Initialize in your project
+vibe init
+
+# Create your first ticket
+vibe new "Add user authentication"
+
+# Start working on it
+vibe start TKT-001
+```
+
+## 🤔 Why VibeKit?
+
+- **🎯 Vibe code with manageable smaller tasks** - Break down complex features into focused tickets
+- **🎮 Stay in control** - You drive the development, AI assists with structure and clarity
+- **🧠 Less model hallucination** - Clear, scoped tickets reduce AI confusion and improve accuracy
+- **📚 Develop docs as you go** - Maintain work history and context with every ticket
+- **🔍 Let models vibe review** - AI can review your work against the original ticket requirements
+- **🚀 AI-native ticket management** - Purpose-built for AI-assisted development workflows
+- **⚡ Generate tickets using Claude Code and Codex power** - Leverage cutting-edge AI for planning
+- **🔄 Seamless git workflow** - Automatic branch creation and status tracking
+- **📝 Living documentation** - Your tickets in git become your project's development story
+
+## ✨ Features
+
+```
+   🎯 Smart Ticket Management    📋 Interactive Lists & Filters
+   🔗 Git Branch Integration     🤖 AI-Powered Enhancement (Claude Code / Codex)
+   📝 Customizable Templates     🔍 Quality Validation & Auto-Fix
+```
+
+- **🎯 Smart Tickets**: Create, manage, and track development tickets with unique IDs
+- **🔗 Git Integration**: Automatic branch creation and workflow management  
+- **🤖 AI Enhancement**: Claude Code integration for ticket refinement and content improvement
+- **📋 Interactive CLI**: Beautiful terminal interface with arrow navigation
+- **📝 Templates**: Customizable ticket templates for consistent workflows
+- **🔍 Quality Control**: Automated linting and validation with auto-fix capabilities
+- **🚀 Quick Actions**: One-command ticket creation, status updates, and more
+
+## 📚 Commands Reference
+
+### 🏗️ Project Setup
+```bash
+# Initialize VibeKit in your project
+vibe init [--with-samples|-s]
+
+# Get started with sample tickets and guide
+vibe get-started
+```
+
+### 🎫 Ticket Management
+```bash
+# Create a new ticket
+vibe new "Fix login bug"
+vibe new "Add dark mode" --priority high --status open
+
+# List all tickets (with optional filtering)
+vibe list
+vibe list --status=open
+
+# Close/complete a ticket
+vibe close TKT-001
+
+# Start working on a ticket (creates git branch)
+vibe start TKT-001
+vibe start TKT-001 --base main --update-status
+```
+
+### 🤖 AI Integration
+```bash
+# Connect Claude Code for ticket enhancement
+vibe link
+
+# Enhance a ticket using Claude with AI
+vibe refine TKT-001
+
+# Interactive refinement with custom goals
+vibe refine TKT-005 "focus on performance and error handling"
+
+# Disconnect AI integration
+vibe unlink
+```
+
+### 🔍 Quality & Validation
+```bash
+# Validate ticket documentation formatting
+vibe lint
+
+# Lint with detailed output including warnings
+vibe lint --verbose
+
+# Automatically fix missing frontmatter fields and sections
+vibe lint --fix
+
+# Lint a specific ticket file
+vibe lint TKT-001-example.md
+```
+
+## 🛠️ Usage Examples
+
+### Creating Your First Workflow
+```bash
+# 1. Initialize your project
+$ vibe init --with-samples
+✅ Created .vibe directory structure
+📝 Added sample tickets and templates
+
+# 2. Create a new feature ticket
+$ vibe new "Add dark mode toggle" --priority high
+🎫 Created TKT-004: Add dark mode toggle
+🤖 Want to enhance with AI? (y/n) y
+
+# 3. Start working on it
+$ vibe start TKT-004
+🌿 Created branch: feature/TKT-004-add-dark-mode-toggle
+📝 Updated ticket status to in_progress
+
+# 4. Check your progress
+$ vibe list
+┌─────────┬──────────────┬─────────────────────────────┐
+│ ID      │ Status       │ Title                       │
+├─────────┼──────────────┼─────────────────────────────┤
+│ TKT-004 │ in_progress  │ Add dark mode toggle        │
+│ TKT-003 │ open         │ Fix responsive layout       │
+│ TKT-002 │ done         │ Setup authentication        │
+└─────────┴──────────────┴─────────────────────────────┘
+```
+
+### Working with AI Enhancement
+```bash
+# Connect Claude Code (one-time setup)
+$ vibe link
+🔗 Configure Claude Code integration
+✨ Enter your API key: [hidden]
+✅ AI features enabled!
+
+# Claude will automatically enhance new tickets
+$ vibe new "Optimize database queries"
+🎫 Created TKT-005: Optimize database queries
+🤖 Enhancing using Claude...
+✨ Added acceptance criteria, technical details, and test plan!
+
+# Or refine existing tickets with AI
+$ vibe refine TKT-003
+▶ Analyzing ticket TKT-003...
+ℹ Found: TKT-003 - Fix responsive layout
+🧠 Analyzing ticket content...
+✨ Generating enhancements...
+
+🔧 Refinement Options
+❯ Apply refinements to ticket
+  Ask for changes/improvements  
+  View diff in terminal
+  Cancel and exit
+
+# View what Claude enhanced before applying
+📊 TICKET REFINEMENT DIFF
+═══════════════════════════════════════
+🔹 Title (refined):
+────────────────────────────────────────
+Fix responsive layout issues in `src/components/Layout.jsx`
+
+🔹 Implementation Notes (refined):
+────────────────────────────────────────
+- Update CSS Grid in `src/styles/layout.css` for mobile breakpoints
+- Add `useMediaQuery()` hook for responsive state management
+- Test on devices: iPhone SE, iPad, desktop (1920px+)
+```
+
+### Quality Control with Lint
+```bash
+# Check all tickets for formatting issues
+$ vibe lint
+🔍 VibeKit Ticket Linter Results
+
+❌ TKT-001-setup.md
+   Error: Missing required frontmatter field: slug
+   Error: Missing required section: ## Implementation Notes
+
+❌ TKT-003-responsive.md
+   Error: Invalid status "in-review". Must be one of: open, in_progress, review, done
+   Error: Section "## Testing & Test Cases" appears to be empty or too short
+
+✅ TKT-002-auth.md
+
+📊 Summary:
+   Files checked: 3
+   Files with issues: 2
+   Total errors: 4
+   Total warnings: 0
+
+💡 Fix the errors above to ensure consistent ticket formatting.
+💡 Use --fix flag to automatically fix missing sections.
+
+# Automatically fix missing fields and sections
+$ vibe lint --fix
+🔍 VibeKit Ticket Linter Results
+
+🔧 TKT-001-setup.md (FIXED)
+   Fixed: 1 missing frontmatter fields and 3 missing sections
+
+❌ TKT-003-responsive.md
+   Error: Invalid status "in-review". Must be one of: open, in_progress, review, done
+
+📊 Summary:
+   Files checked: 3
+   Files with issues: 1
+   Files fixed: 1
+   Total errors: 1
+   Total warnings: 1
+
+🎉 Most issues have been fixed! Please review and fix remaining errors manually.
+```
+
+## ⚙️ Configuration
+
+VibeKit creates a `.vibe` directory in your project root:
+
+```
+📁 .vibe/
+  ├── 📋 config.yml           # Main configuration
+  ├── 📁 .templates/          # Ticket templates
+  │   └── 📄 default.md       # Default ticket template
+  ├── 📁 tickets/             # Your ticket files
+  │   ├── 🎫 TKT-001-setup.md
+  │   └── 🎫 TKT-002-auth.md
+  └── 📄 README.md           # Project guidance
+```
+
+### Sample config.yml
+```yaml
+# Project settings
+project:
+  name: vibekit
+  description: CLI tool for managing tickets, project context, and AI suggestions
+
+# Ticket settings
+tickets:
+  path: .vibe/tickets
+  id_format: TKT-{number}
+  default_template: .vibe/.templates/default.md
+  use_status_folders: false
+  slug:
+    max_length: 30
+    word_limit: 5
+  status_options:
+    - open
+    - in_progress
+    - review
+    - done
+  priority_options:
+    - low
+    - medium
+    - high
+    - critical
+
+# AI integration
+ai:
+  enabled: true
+  provider: claude-code
+
+# Git integration
+git:
+  branch_prefix: feature/
+  default_base: main
+
+# Hooks
+hooks:
+  pre_commit: false
+  post_checkout: false
+```
+
+## 🤝 Contributing & Feedback
+
+We'd love your help making VibeKit better! Here's how you can contribute:
+
+- 🐛 **Report bugs** → [GitHub Issues](https://github.com/vibedx/vibekit/issues)
+- 💡 **Suggest features** → [Discussions](https://github.com/vibedx/vibekit/discussions)  
+- 🔧 **Submit PRs** → [Contributing Guide](https://github.com/vibedx/vibekit/blob/main/CONTRIBUTING.md)
+- ⭐ **Star the repo** → Show your support!
+
+### Development Setup
+```bash
+git clone https://github.com/vibedx/vibekit.git
+cd vibekit
+npm install
+npm start  # Watch mode
+```
+
+## 👥 Contributors
+
+<div align="center">
+
+*Thank you to everyone who helps make VibeKit better!*
+
+**Maintainer**: [Ives van Hoorne](https://github.com/ivesvan) 
+
+*Want to see your name here? [Contribute to the project!](https://github.com/vibedx/vibekit/blob/main/CONTRIBUTING.md)*
+
+</div>
+
+## Release Preparation
+
+### Prerequisites
+- [ ] NPM account with publish permissions
+- [ ] All features tested and working
+- [ ] Documentation updated
+- [ ] CHANGELOG.md updated (if applicable)
+
+### Release Steps
+1. **Test the build**: `npm start` to verify everything works
+2. **Version bump**: 
+   - Patch: `npm version patch` (bug fixes)
+   - Minor: `npm version minor` (new features)
+   - Major: `npm version major` (breaking changes)
+3. **Publish**: `npm publish --access=public` (for scoped packages)
+4. **Verify**: `npm info @vibedx/vibekit` to confirm publication
+
+### Pre-Release Checklist
+- [ ] All commands work as expected
+- [ ] No sensitive data in published files
+- [ ] Package.json metadata is correct
+- [ ] README reflects current functionality
+- [ ] Version number follows semantic versioning
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch
+3. Commit your changes
+4. Push to the branch
+5. Create a Pull Request
+
+## License
+
+MIT

package/assets/config.yml

@@ -0,0 +1,35 @@
+# VibeKit Configuration
+# Created: 2025-05-27
+
+project:
+  name: ""
+  description: ""
+
+tickets:
+  path: ".vibe/tickets"
+  id_format: "TKT-{number}"
+  default_template: ".vibe/.templates/default.md"
+  use_status_folders: false
+  status_options:
+    - open
+    - in_progress
+    - review
+    - done
+  priority_options:
+    - low
+    - medium
+    - high
+    - critical
+
+ai:
+  enabled: false
+  provider: "none"
+
+hooks:
+  pre_commit: false
+  post_checkout: false
+
+review:
+  acceptance_threshold: 80
+  good_threshold: 80
+  warning_threshold: 60

package/assets/default.md

@@ -0,0 +1,47 @@
+---
+id: TKT-{id}
+title: {title}
+slug: {slug}
+status: open
+priority: medium
+created_at: {date}
+updated_at: {date}
+---
+
+## Description
+
+<!-- Write the task details, requirements, and any other relevant information here. -->
+
+## Acceptance Criteria
+
+<!-- List the specific conditions that must be met for this ticket to be considered complete. -->
+
+## Code Quality
+
+<!-- List the specific conditions that must be met for this ticket to be considered complete. -->
+
+## Implementation Notes
+
+<!-- Technical details, references, or implementation context that might be helpful. -->
+
+## Design / UX Considerations
+
+<!-- Add any design links (Figma, etc.) or UX considerations here. -->
+
+## Testing & Test Cases
+
+<!-- Brief, focused test cases and verification steps. Keep concise. -->
+
+## AI Prompt
+
+<!-- Add the AI instructions or input prompt here. For example, explain what needs to be generated or reviewed by AI. -->
+
+## Expected AI Output
+
+<!-- (Optional) Describe the kind of output or format you expect from the AI — code, checklist, response, etc. -->
+
+
+## AI Workflow
+
+<!-- NOTE (Do not remove) -->
+Always use `vibe start` to start working on this ticket and `vibe close` to close this ticket when done. Keep tickets up to date with implementation details and progress. Read .vibe/.context/aiworkflow directory for following vibekit cli workflow and follow the instructions to work on the tickets.

package/assets/instructions/README.md

@@ -0,0 +1,46 @@
+# AI Instructions Templates
+
+This directory contains instruction templates for different AI coding assistants that can be used with VibeKit.
+
+## Files
+
+### `claude.md`
+Template for Claude Code (Anthropic) instructions. This file is copied to `.context/instructions/claude.md` when running `vibe link` to configure Claude Code integration.
+
+### `codex.md`
+Placeholder template for future OpenAI Codex integration. Coming soon.
+
+## How It Works
+
+1. **Templates stored here** - All AI instruction templates are maintained in `assets/instructions/`
+2. **Copied on link** - When running `vibe link`, the appropriate template is copied to `.context/instructions/`
+3. **AI reads from .context** - AI assistants automatically read instructions from `.context/instructions/`
+
+## Adding New AI Providers
+
+To add support for a new AI provider:
+
+1. Create a new template file: `assets/instructions/{provider}.md`
+2. Update the link command to handle the new provider
+3. Ensure the template follows VibeKit's ticket-driven workflow
+
+## Directory Structure
+
+```
+assets/instructions/
+├── README.md         # This file
+├── claude.md         # Claude Code template
+└── codex.md          # OpenAI Codex template (placeholder)
+
+.context/instructions/ (created by vibe link)
+├── README.md         # Generated documentation
+├── claude.md         # Active Claude instructions
+└── codex.md          # Active Codex instructions (when available)
+```
+
+## Best Practices
+
+- Keep instructions focused on VibeKit's ticket-driven workflow
+- Include clear command references and examples
+- Emphasize the "ticket-first" approach for all changes
+- Update templates when adding new VibeKit features

package/assets/instructions/claude.md

@@ -0,0 +1,83 @@
+# VibeKit Instructions for Claude
+
+⚠️ **IMPORTANT**: Only modify this file if you understand that Claude Code will use these instructions as workflow guidelines for this project. These instructions will be automatically followed by Claude when working in this codebase.
+
+## 🎯 PRIMARY RULE: Always Work Through Tickets
+This project uses VibeKit for organized development. **For ANY task, feature, or bug fix:**
+
+1. **Create a ticket first**: `vibe new`
+2. **Start working**: `vibe start <ticket-id>` 
+3. **Track progress**: `vibe list`
+4. **Close when done**: `vibe close <ticket-id>`
+
+## 📋 VibeKit Commands Reference
+- `vibe new` - Create new ticket (ALWAYS do this first!)
+- `vibe list` - List all tickets with status
+- `vibe start <id>` - Start working on ticket (creates/switches branch)
+- `vibe close <id>` - Close ticket and merge branch
+- `vibe link` - Configure AI provider (Claude Code)
+- `vibe unlink` - Disable AI features
+
+## 🔄 Mandatory Workflow Rules
+1. **NO direct code changes** - Always create a ticket first with `vibe new`
+2. **Descriptive tickets** - Clear title and detailed acceptance criteria
+3. **One feature per ticket** - Keep scope focused and manageable
+4. **Branch per ticket** - `vibe start` handles branch creation automatically
+5. **Ticket-driven development** - Even for small changes or fixes
+
+## 🏗️ Ticket Structure
+Located in `.vibe/tickets/` with YAML frontmatter:
+- id, title, status, priority
+- created_at, updated_at timestamps
+- Detailed description and acceptance criteria
+
+## 🔐 AI Integration
+- Claude Code integrated via Anthropic API
+- Uses environment variables (ANTHROPIC_API_KEY) or .env files
+- No credentials stored in config files
+- Configuration via `vibe link`
+
+## 💡 Best Practices for Claude
+- Always start with `vibe new` before any code changes
+- Use clear, descriptive ticket titles
+- Include detailed acceptance criteria in tickets
+- Follow the branch workflow via `vibe start`
+- Keep tickets focused and actionable
+- Reference ticket IDs in commits
+
+## ✍️ Ticket Content Guidelines
+When refining or creating tickets, use technical, developer-friendly formatting:
+
+### Code Formatting
+- File paths: `src/components/Button.jsx`, `package.json`, `README.md`
+- Commands: `vibe init`, `npm install`, `git commit -m "message"`
+- Functions: `handleClick()`, `useState()`, `createSlug()`
+- Variables: `isLoading`, `userInput`, `selectedIndex`
+- Code snippets for any code examples or configuration
+
+### Content Structure
+- Keep "Testing & Test Cases" section brief (2-4 key test points maximum)
+- Use "Implementation Notes" instead of "Notes" for technical details
+- Be specific about file paths, function names, and technical requirements
+- Include specific acceptance criteria with technical details
+- Reference exact file locations and function signatures when relevant
+
+### Technical Language
+- Use precise technical terminology
+- Include specific error handling requirements
+- Mention performance considerations when relevant
+- Reference specific libraries, frameworks, or APIs being used
+
+## 🚀 Example Workflow
+```bash
+# User asks: "Add a dark mode toggle"
+vibe new  # Create ticket first
+vibe start TKT-XXX  # Start working on the ticket
+# Make changes, commit with ticket reference
+vibe close TKT-XXX  # Close when complete
+```
+
+**Remember: VibeKit promotes organized, ticket-driven development. Always create tickets first!**
+
+---
+*This file is automatically created by VibeKit. Future versions will support Codex and other AI providers.*

package/assets/instructions/codex.md

@@ -0,0 +1,19 @@
+# VibeKit Instructions for OpenAI Codex
+
+🚧 **COMING SOON**: OpenAI Codex integration for VibeKit
+
+This file will contain instructions for OpenAI Codex when support is added to VibeKit.
+
+## Planned Features
+- Automatic code generation for tickets
+- Code review and improvement suggestions
+- Test case generation
+- Documentation generation
+
+## Current Status
+OpenAI Codex support is planned for a future release. 
+
+For now, use Claude Code integration with `vibe link`.
+
+---
+*This file is a placeholder for future OpenAI Codex integration.*