@vibedx/vibekit 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibedx/vibekit",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "A powerful CLI tool for managing development tickets and project workflows",
   "main": "index.js",
   "type": "module",
@@ -8,7 +8,8 @@
     "index.js",
     "src/",
     "assets/",
-    "skills/"
+    "skills/",
+    "vibekit-plugin/"
   ],
   "bin": {
     "vibe": "index.js"

package/vibekit-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "vibekit",
+  "displayName": "VibeKit — Ticket-Driven Development",
+  "version": "0.1.0",
+  "description": "Structured ticket workflows, agent orchestration, and worktree isolation for AI-assisted development",
+  "author": "vibedx",
+  "repository": "https://github.com/vibedx/vibekit",
+  "homepage": "https://github.com/vibedx/vibekit",
+  "keywords": ["tickets", "workflow", "agents", "worktrees"],
+  "skills": [
+    "skills/vibekit-workflow",
+    "skills/ticket-writer"
+  ],
+  "agents": [
+    "agents/ticket-worker.md",
+    "agents/reviewer.md"
+  ],
+  "hooks": "hooks/hooks.json",
+  "settings": "settings.json"
+}

package/vibekit-plugin/README.md

@@ -0,0 +1,57 @@
+# VibeKit — Claude Code Plugin
+
+Ticket-driven development workflows for Claude Code. Install once; every project with a `.vibe/` directory gets structured ticket workflows, agent orchestration, and worktree isolation.
+
+## Install
+
+```
+/plugin install vibekit
+```
+
+Or from the community marketplace browser in Claude Code.
+
+## What's included
+
+**Skills**
+- `vibekit-workflow` — teaches Claude the full ticket-driven workflow (create → start → implement → close)
+- `ticket-writer` — helps write well-structured tickets with actionable acceptance criteria
+
+**Agents**
+- `ticket-worker` — autonomous agent that reads a ticket, implements it, and closes it
+- `reviewer` — reviews a completed ticket against its acceptance criteria
+
+**Hooks**
+- `SessionStart` — detects `.vibe/` directory and surfaces open ticket counts on session start
+
+## Requirements
+
+The VibeKit CLI is optional but recommended for full functionality:
+
+```bash
+npm install -g @vibedx/vibekit
+```
+
+Without the CLI, skills and agents still work — you just won't get the `vibe` commands for branch management and ticket status updates.
+
+## Quick start
+
+```bash
+# In any project
+vibe init                                    # set up .vibe/ directory
+vibe new "Add user auth" --priority high -n  # create a ticket
+vibe start TKT-001                           # start working (creates branch)
+# ... implement the work ...
+vibe close TKT-001                           # mark done
+```
+
+Or let an agent do it:
+
+```bash
+vibe start TKT-001 --agent   # spawns Claude agent to work on the ticket autonomously
+```
+
+## Links
+
+- [VibeKit repo](https://github.com/vibedx/vibekit)
+- [npm package](https://www.npmjs.com/package/@vibedx/vibekit)
+- [Claude Code plugin docs](https://code.claude.com/docs/en/discover-plugins)

package/vibekit-plugin/agents/reviewer.md

@@ -0,0 +1,47 @@
+---
+name: reviewer
+description: Reviews a completed VibeKit ticket against its acceptance criteria. Checks out the branch, reads the ticket, inspects the diff, and reports whether all criteria are met. Use after a ticket-worker agent has finished, or before merging a PR.
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+---
+
+You are a senior code reviewer. Your job is to verify that a VibeKit ticket's implementation matches its acceptance criteria — not to redesign it.
+
+## Workflow
+
+1. **Read the ticket** — `cat .vibe/tickets/TKT-XXX-*.md`. Extract the acceptance criteria.
+
+2. **Inspect the diff** — `git diff main...HEAD` (or the relevant base branch). Understand what changed.
+
+3. **Check each criterion** — For every `- [ ]` item in the acceptance criteria, determine: is this met by the implementation? Be concrete — quote code or explain what's missing.
+
+4. **Run tests if present** — `npm test` / `pytest` / whatever the project uses. A failing test suite is a blocking issue.
+
+5. **Report** — Produce a structured review:
+
+```
+## TKT-XXX Review
+
+### ✅ Passing criteria
+- [ ] Criterion 1 — met: <brief evidence>
+- [ ] Criterion 2 — met: <brief evidence>
+
+### ❌ Failing criteria
+- [ ] Criterion 3 — NOT met: <what's missing and where>
+
+### Code notes
+<Optional: any non-blocking observations about code quality, style, or potential bugs>
+
+### Verdict
+APPROVED / NEEDS WORK
+```
+
+## Rules
+
+- Judge against the ticket's criteria, not your personal preferences. If it meets criteria, approve it even if you'd have done it differently.
+- Be specific about failures. "It doesn't work" is not useful. "The redirect on line 42 of auth.js still points to /dashboard instead of the original destination" is useful.
+- Don't block on style issues. Note them, but don't fail the review for them.
+- If acceptance criteria are too vague to verify, flag that in your review — it's a ticket quality issue, not an implementation issue.

package/vibekit-plugin/agents/ticket-worker.md

@@ -0,0 +1,47 @@
+---
+name: ticket-worker
+description: Works autonomously on a single VibeKit ticket. Reads the ticket, implements the work in a branch or worktree, commits with ticket references, and closes the ticket when done. Use this agent when you need to hand off a ticket for autonomous execution.
+tools:
+  - Bash
+  - Read
+  - Edit
+  - Write
+  - Glob
+  - Grep
+---
+
+You are a senior software engineer executing a VibeKit ticket. Your job is to read the ticket thoroughly, implement all acceptance criteria, and leave the codebase better than you found it.
+
+## Workflow
+
+1. **Read the ticket** — `cat .vibe/tickets/TKT-XXX-*.md`. Understand what's needed and why before touching any code.
+
+2. **Start the ticket** — `vibe start TKT-XXX`. This creates the feature branch and marks the ticket `in_progress`.
+
+3. **Implement** — Work through the acceptance criteria systematically. Commit after each logical unit of work:
+   ```bash
+   git commit -m "TKT-XXX: descriptive message about what this commit does"
+   ```
+
+4. **Verify** — Check every acceptance criterion is met. Run tests if they exist. Don't close until all criteria pass.
+
+5. **Close** — `vibe close TKT-XXX`. This marks the ticket `done`.
+
+6. **Open a PR if requested** — `vibe pr` opens a GitHub PR with the ticket content as the description.
+
+## Rules
+
+- Read the full ticket before writing any code. Misunderstanding scope is the most common failure.
+- Commit early and often with ticket references. Each commit message should start with `TKT-XXX:`.
+- If you hit a blocker that requires a product decision, update the ticket with your finding and stop — don't guess.
+- Do not add features beyond what the acceptance criteria require. Scope creep wastes time.
+- Leave no commented-out code, no TODO comments, and no half-finished work in commits.
+
+## On Ambiguity
+
+If the ticket is unclear on a specific point, use best judgment for code-level decisions (naming, structure, patterns) but flag any product-level uncertainty in the ticket before closing:
+
+```bash
+# Append a note to the ticket
+echo "\n## Blockers\n- [ ] Need decision on X before this can be fully closed" >> .vibe/tickets/TKT-XXX-*.md
+```

package/vibekit-plugin/hooks/detect-vibe.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# SessionStart hook — detect .vibe/ and emit context for Claude
+
+if [ -d ".vibe" ]; then
+  echo "VibeKit project detected."
+
+  if command -v vibe &>/dev/null; then
+    OPEN=$(vibe list --status=open 2>/dev/null | wc -l | tr -d ' ')
+    IN_PROGRESS=$(vibe list --status=in_progress 2>/dev/null | wc -l | tr -d ' ')
+    echo "Tickets: ${IN_PROGRESS} in progress, ${OPEN} open."
+    echo "Use 'vibe list' to see tickets, 'vibe start TKT-XXX' to begin work."
+  else
+    echo "Install vibekit CLI: npm install -g @vibedx/vibekit"
+  fi
+fi

package/vibekit-plugin/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+  "hooks": [
+    {
+      "event": "SessionStart",
+      "description": "Detect .vibe/ directory and load ticket context",
+      "command": "bash hooks/detect-vibe.sh"
+    },
+    {
+      "event": "PostToolUse",
+      "matcher": {
+        "tool": "Bash",
+        "pattern": "git commit"
+      },
+      "description": "Remind agent to update ticket status after commits"
+    }
+  ]
+}

package/vibekit-plugin/settings.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(vibe *)",
+      "Bash(git *)"
+    ]
+  },
+  "env": {}
+}

package/vibekit-plugin/skills/ticket-writer/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: ticket-writer
+description: Write well-structured VibeKit tickets. Use when the user asks to create a ticket, document a task, or break down a feature into trackable work items. Ensures tickets have clear descriptions, acceptance criteria, and implementation notes before any code is written.
+license: MIT
+---
+
+# VibeKit Ticket Writer
+
+Write tickets that are immediately actionable — no refinement needed. Every ticket should answer: what, why, and how to verify it's done.
+
+## 🔴 RULE: Always use `-n` when creating tickets programmatically
+
+```bash
+vibe new "title" --assignee <username> --priority <level> -n
+```
+
+The `-n` / `--no-interactive` flag skips the AI enhancement prompt, which would otherwise block automation.
+
+## What Makes a Good Ticket
+
+**Description** — What needs to be done and why. Include context the implementer needs. Two to five sentences is usually right.
+
+**Acceptance Criteria** — Concrete, checkable conditions. Not "it works" but "clicking Submit saves the form and shows a success toast". Write these as `- [ ]` checkboxes.
+
+**Implementation Notes** — File paths, API references, known constraints, or design decisions that save the implementer time.
+
+## Template
+
+```bash
+vibe new "Clear action-oriented title" \
+  --assignee <username> \
+  --priority high \
+  --description "What needs to happen and why. Reference the relevant product area or user flow. Note any constraints or dependencies." \
+  --acceptance-criteria "- [ ] Specific, observable outcome 1
+- [ ] Specific, observable outcome 2
+- [ ] Edge case handled: <description>" \
+  -n
+```
+
+## Priority Guide
+
+| Priority | Use when |
+|----------|----------|
+| `critical` | Blocking release, production incident |
+| `high` | Current sprint, clear business need |
+| `medium` | Planned work, next 1-2 sprints |
+| `low` | Nice to have, backlog |
+
+## Examples
+
+```bash
+# Feature
+vibe new "Add dark mode toggle to settings" \
+  --assignee alice \
+  --priority medium \
+  --description "Users want to reduce eye strain. Add a toggle in Settings > Appearance that persists the preference to localStorage and applies a 'dark' class to <html>." \
+  --acceptance-criteria "- [ ] Toggle appears in Settings > Appearance
+- [ ] Preference persists across page reloads
+- [ ] All components respect dark mode colors from design tokens
+- [ ] Toggle is keyboard accessible" \
+  -n
+
+# Bug fix
+vibe new "Fix login redirect loop on expired session" \
+  --assignee bob \
+  --priority high \
+  --description "When a session expires mid-navigation, the auth middleware redirects to /login, which redirects back to the protected page, creating an infinite loop. Need to clear the redirect target when session is expired." \
+  --acceptance-criteria "- [ ] Expired session redirects to /login once (no loop)
+- [ ] After login, user lands on the originally requested page
+- [ ] Verified in Chrome, Firefox, Safari" \
+  -n
+```
+
+## After Creating
+
+```bash
+vibe start TKT-XXX   # creates branch, marks in_progress
+# do the work
+vibe close TKT-XXX   # marks done
+```

package/vibekit-plugin/skills/vibekit-workflow/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: vibekit
+description: Ticket-driven development workflow for AI coding agents using VibeKit CLI. Use when the user asks to create a task, feature, bug fix, or ticket; mentions "vibe new", "vibe list", or vibekit commands; or wants structured, scoped work breakdown. Triggers on phrases like "add a ticket", "track this task", "break this down", or "start a new feature". Helps agents create focused tickets with clear acceptance criteria before writing code.
+license: MIT
+---
+
+# VibeKit — Ticket-Driven Development
+
+VibeKit is a CLI for managing development tickets and AI-assisted workflows. This skill teaches agents how to use vibekit properly — create tickets before coding, work through them systematically, and keep tickets as living documentation.
+
+## 🔴 MANDATORY RULE: Always Create a Ticket First
+
+**Before writing ANY code on a repo that has a `.vibe/` directory, you MUST create a vibekit ticket.** No exceptions for features, bug fixes, refactors, or multi-step tasks.
+
+This is not a suggestion — it's the core workflow. If the user asks you to "add X", "fix Y", or "build Z", your first action should be:
+
+```bash
+vibe new "descriptive title" --assignee <your-username> --priority <level> -n
+```
+
+Then read the ticket, plan the work, and `vibe start TKT-XXX` before touching any code.
+
+**Only skip the ticket for truly trivial changes**: typo fixes, single-line config tweaks, or answering a quick question.
+
+## Why This Matters
+
+Tickets break work into scoped, focused chunks that reduce AI drift and create documentation as a side effect. They also give humans a clear trail of what was done and why — critical for collaboration between humans and agents.
+
+```bash
+# 1. Create a ticket
+vibe new "Add user authentication" --assignee <username> --priority high -n
+
+# 2. Start working (creates git branch feature/TKT-XXX-slug)
+vibe start TKT-001
+
+# 3. Implement the work, commit with ticket reference
+git commit -m "TKT-001: add login endpoint"
+
+# 4. Close when done
+vibe close TKT-001
+```
+
+## Installation
+
+```bash
+npm install -g @vibedx/vibekit
+```
+
+Then in any project:
+```bash
+vibe init          # Creates .vibe/ directory with config, team, templates
+```
+
+## Core Commands
+
+| Command | Purpose |
+|---------|---------|
+| `vibe init` | Initialize vibekit in a project |
+| `vibe new "title"` | Create a ticket |
+| `vibe list` | List all tickets |
+| `vibe start <id>` | Start work (creates git branch) |
+| `vibe start <id> --worktree` | Start work in a separate worktree |
+| `vibe start <id> --agent` | Spawn a Claude agent to work on the ticket |
+| `vibe start <id> <id2> -w --agent` | Spawn agents in parallel worktrees |
+| `vibe status` | Show active worktrees and ticket progress |
+| `vibe pr` | Open a GitHub PR from the current ticket branch |
+| `vibe pr --all` | Open PRs for all worktree branches |
+| `vibe close <id>` | Mark ticket done (cleans up worktree if any) |
+| `vibe lint` | Validate ticket format |
+| `vibe lint --fix` | Auto-fix missing sections |
+| `vibe refine <id>` | AI-enhance ticket details |
+| `vibe plan to-ticket <file>` | Convert a saved plan into tickets (AI) |
+| `vibe swarm` | Spawn parallel agents across open tickets in worktrees |
+| `vibe team` | Manage team members |
+
+## Creating Tickets (for AI agents)
+
+**Always use `-n` / `--no-interactive` when creating tickets programmatically.** This skips the AI enhancement prompt which would otherwise block automation.
+
+```bash
+vibe new "Fix login redirect loop" --assignee alice --priority high -n
+vibe new "Add dark mode" --assignee bob --author alice -n
+```
+
+### Useful flags
+
+- `--priority low|medium|high|critical` (default: medium)
+- `--status open|in_progress|review|done` (default: open)
+- `--assignee <username>` — who works on it
+- `--author <username>` — who created it
+- `-d` / `--description "text"` — pre-fill the Description section
+- `--acceptance-criteria "- [ ] criterion 1\n- [ ] criterion 2"` — pre-fill Acceptance Criteria
+- `-n` / `--no-interactive` — skip AI enhancement prompt
+
+**AI agents should always provide `--description` and `--acceptance-criteria` when creating tickets.** This ensures tickets are actionable immediately without needing `vibe refine`. Fill in as much detail as possible based on the task context.
+
+## Ticket Structure
+
+Tickets live in `.vibe/tickets/` as markdown files with YAML frontmatter:
+
+```markdown
+---
+id: TKT-001
+title: Add user authentication
+slug: TKT-001-add-user-authentication
+status: open
+priority: high
+assignee: "alice"
+author: "bob"
+created_at: 2026-04-11T10:00:00Z
+updated_at: 2026-04-11T10:00:00Z
+---
+
+## Description
+What needs to be done and why.
+
+## Acceptance Criteria
+- [ ] Concrete checkbox 1
+- [ ] Concrete checkbox 2
+
+## Implementation Notes
+Technical details, file paths, API references.
+
+## Testing & Test Cases
+Brief test scenarios.
+```
+
+## Filtering Tickets
+
+```bash
+vibe list                       # All tickets
+vibe list --status=open         # Only open
+vibe list --assignee=alice      # Only alice's tickets
+```
+
+## Team Management
+
+Teams are stored in `.vibe/team.yml`. Assignee values in tickets should match team member IDs.
+
+```bash
+vibe team add alice --name "Alice" --github alice --slack U0ABC123 --role Engineer
+vibe team                       # List members
+vibe team show alice            # Show one member
+```
+
+## When to Use This Skill
+
+Apply vibekit workflow when:
+
+- User asks to "add a feature", "fix a bug", "implement X", "build Y"
+- Task is non-trivial (more than a one-line fix)
+- Work touches multiple files or requires planning
+- User mentions `vibe`, tickets, tracking, or task management
+- Working in a project that has a `.vibe/` directory
+
+**Don't force tickets for trivial changes** — typo fixes, config tweaks, or single-line edits can skip the ticket workflow.
+
+## Integration with Git
+
+`vibe start TKT-001` automatically:
+1. Creates branch `feature/TKT-001-<slug>` (or configured prefix)
+2. Updates ticket status to `in_progress`
+3. Switches to the new branch
+
+`vibe close TKT-001`:
+1. Updates ticket status to `done`
+2. Leaves the branch for manual merge/PR
+
+### Worktree Support (Parallel Development)
+
+Use `--worktree` / `-w` to work on multiple tickets simultaneously without switching branches:
+
+```bash
+# Start ticket in a dedicated worktree
+vibe start TKT-002 --worktree
+
+# The worktree is created at ~/.vibekit/worktrees/<repo>/<branch>/
+# Your main working directory stays on its current branch
+# cd into the worktree path to work on the ticket
+
+# Close automatically removes the worktree
+vibe close TKT-002
+
+# If the worktree has uncommitted changes, use --force
+vibe close TKT-002 --force
+```
+
+`vibe list` shows a 🌿 indicator next to tickets with active worktrees.
+
+### Spawning Claude Agents
+
+Use `--agent` to spawn a Claude Code agent that autonomously works on a ticket:
+
+```bash
+# Single ticket — agent works in the current directory
+vibe start TKT-003 --agent
+
+# Multiple tickets — each gets its own worktree + agent
+vibe start TKT-003 TKT-004 TKT-005 -w --agent
+```
+
+Agents automatically:
+- Read the ticket requirements and implement the work
+- Commit changes with ticket references
+- Mark the ticket as `done` when complete (or `in_progress` if further changes needed)
+- Have full tool access (git, file I/O, CLI)
+- Receive the vibekit skill context so they know how to use vibe commands
+
+Agent timeout defaults to 15 minutes (900s). Configure in `.vibe/config.yml`:
+
+```yaml
+worktree:
+  agent:
+    timeout: 900  # seconds
+```
+
+### Opening Pull Requests
+
+Use `vibe pr` to open GitHub PRs from ticket branches:
+
+```bash
+# PR for the current branch
+vibe pr
+
+# PRs for specific tickets
+vibe pr TKT-003 TKT-004
+
+# PRs for all worktree branches
+vibe pr --all
+
+# Draft PR
+vibe pr --draft
+```
+
+PR title and body are auto-populated from ticket content. Ticket status is set to `review`.
+
+### Plans → Tickets
+
+When you (Claude) produce an implementation plan, save it to `.vibe/plans/` as a
+markdown file, then turn it into tickets:
+
+```bash
+# Preview the tickets vibekit would extract from a plan (no files written)
+vibe plan to-ticket .vibe/plans/my-feature.md
+
+# Create the tickets once the breakdown looks right
+vibe plan to-ticket .vibe/plans/my-feature.md --auto
+
+# Dry-run shows the extracted items without creating anything
+vibe plan to-ticket .vibe/plans/my-feature.md --dry-run
+```
+
+The command sends the plan to Claude, which extracts discrete work items
+(title, description, acceptance criteria, priority, estimate) and writes one
+ticket per item to `.vibe/tickets/`. Default is preview-then-confirm: it shows
+the breakdown and only writes files when you pass `--auto`. Chain it with
+`vibe start TKT-XXX` to begin work.
+
+### Swarming (Parallel Agents)
+
+`vibe swarm` spins up multiple Claude agents at once, each in its own worktree,
+to burn down a batch of tickets in parallel:
+
+```bash
+# Swarm all open tickets (capped by config swarm.maxAgents, default 3)
+vibe swarm
+
+# Limit the number of concurrent agents
+vibe swarm --count 5
+
+# Only swarm tickets matching a filter (frontmatter key:value)
+vibe swarm --filter priority:high
+
+# Use a specific base branch for the worktrees
+vibe swarm --base main
+
+# Check on a running swarm
+vibe swarm status
+```
+
+Configure caps and timeout in `.vibe/config.yml`:
+
+```yaml
+swarm:
+  maxAgents: 3
+  timeout: 900  # seconds
+```
+
+### Monitoring Progress
+
+```bash
+# Show active worktrees and agent status
+vibe status
+
+# List in-progress tickets
+vibe list --status=in_progress
+```
+
+## Automation Pattern
+
+For bots and automated agents working through tickets:
+
+```bash
+# Find open tickets assigned to you
+vibe list --assignee=mybotname --status=open
+
+# For each ticket:
+# 1. Read .vibe/tickets/TKT-XXX-*.md for full context
+# 2. Do the work on branch feature/<ticket-id>-<slug>
+# 3. Commit changes
+# 4. Open PR: vibe pr
+# 5. Close: vibe close TKT-XXX
+```
+
+## Links
+
+- Repo: https://github.com/vibedx/vibekit
+- npm: https://www.npmjs.com/package/@vibedx/vibekit
+- Issues: https://github.com/vibedx/vibekit/issues