@vibedx/vibekit 0.8.8 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/README.md +34 -0
  2. package/index.js +1 -1
  3. package/package.json +3 -2
  4. package/skills/vibekit/SKILL.md +54 -0
  5. package/src/commands/init/index.js +2 -1
  6. package/src/commands/plan/index.js +283 -0
  7. package/src/commands/plan/index.test.js +127 -0
  8. package/src/commands/plan/to-ticket.js +312 -0
  9. package/src/commands/plan/to-ticket.test.js +149 -0
  10. package/vibekit-plugin/.claude-plugin/plugin.json +20 -0
  11. package/vibekit-plugin/README.md +57 -0
  12. package/vibekit-plugin/agents/reviewer.md +47 -0
  13. package/vibekit-plugin/agents/ticket-worker.md +47 -0
  14. package/vibekit-plugin/hooks/detect-vibe.sh +15 -0
  15. package/vibekit-plugin/hooks/hooks.json +17 -0
  16. package/vibekit-plugin/settings.json +9 -0
  17. package/vibekit-plugin/skills/ticket-writer/SKILL.md +80 -0
  18. package/vibekit-plugin/skills/vibekit-workflow/SKILL.md +319 -0
package/vibekit-plugin/skills/ticket-writer/SKILL.md ADDED
@@ -0,0 +1,80 @@
1
+ ---
2
+ name: ticket-writer
3
+ 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.
4
+ license: MIT
5
+ ---
6
+
7
+ # VibeKit Ticket Writer
8
+
9
+ Write tickets that are immediately actionable — no refinement needed. Every ticket should answer: what, why, and how to verify it's done.
10
+
11
+ ## 🔴 RULE: Always use `-n` when creating tickets programmatically
12
+
13
+ ```bash
14
+ vibe new "title" --assignee <username> --priority <level> -n
15
+ ```
16
+
17
+ The `-n` / `--no-interactive` flag skips the AI enhancement prompt, which would otherwise block automation.
18
+
19
+ ## What Makes a Good Ticket
20
+
21
+ **Description** — What needs to be done and why. Include context the implementer needs. Two to five sentences is usually right.
22
+
23
+ **Acceptance Criteria** — Concrete, checkable conditions. Not "it works" but "clicking Submit saves the form and shows a success toast". Write these as `- [ ]` checkboxes.
24
+
25
+ **Implementation Notes** — File paths, API references, known constraints, or design decisions that save the implementer time.
26
+
27
+ ## Template
28
+
29
+ ```bash
30
+ vibe new "Clear action-oriented title" \
31
+ --assignee <username> \
32
+ --priority high \
33
+ --description "What needs to happen and why. Reference the relevant product area or user flow. Note any constraints or dependencies." \
34
+ --acceptance-criteria "- [ ] Specific, observable outcome 1
35
+ - [ ] Specific, observable outcome 2
36
+ - [ ] Edge case handled: <description>" \
37
+ -n
38
+ ```
39
+
40
+ ## Priority Guide
41
+
42
+ | Priority | Use when |
43
+ |----------|----------|
44
+ | `critical` | Blocking release, production incident |
45
+ | `high` | Current sprint, clear business need |
46
+ | `medium` | Planned work, next 1-2 sprints |
47
+ | `low` | Nice to have, backlog |
48
+
49
+ ## Examples
50
+
51
+ ```bash
52
+ # Feature
53
+ vibe new "Add dark mode toggle to settings" \
54
+ --assignee alice \
55
+ --priority medium \
56
+ --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>." \
57
+ --acceptance-criteria "- [ ] Toggle appears in Settings > Appearance
58
+ - [ ] Preference persists across page reloads
59
+ - [ ] All components respect dark mode colors from design tokens
60
+ - [ ] Toggle is keyboard accessible" \
61
+ -n
62
+
63
+ # Bug fix
64
+ vibe new "Fix login redirect loop on expired session" \
65
+ --assignee bob \
66
+ --priority high \
67
+ --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." \
68
+ --acceptance-criteria "- [ ] Expired session redirects to /login once (no loop)
69
+ - [ ] After login, user lands on the originally requested page
70
+ - [ ] Verified in Chrome, Firefox, Safari" \
71
+ -n
72
+ ```
73
+
74
+ ## After Creating
75
+
76
+ ```bash
77
+ vibe start TKT-XXX # creates branch, marks in_progress
78
+ # do the work
79
+ vibe close TKT-XXX # marks done
80
+ ```
package/vibekit-plugin/skills/vibekit-workflow/SKILL.md ADDED
@@ -0,0 +1,319 @@
1
+ ---
2
+ name: vibekit
3
+ 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.
4
+ license: MIT
5
+ ---
6
+
7
+ # VibeKit — Ticket-Driven Development
8
+
9
+ 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.
10
+
11
+ ## 🔴 MANDATORY RULE: Always Create a Ticket First
12
+
13
+ **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.
14
+
15
+ 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:
16
+
17
+ ```bash
18
+ vibe new "descriptive title" --assignee <your-username> --priority <level> -n
19
+ ```
20
+
21
+ Then read the ticket, plan the work, and `vibe start TKT-XXX` before touching any code.
22
+
23
+ **Only skip the ticket for truly trivial changes**: typo fixes, single-line config tweaks, or answering a quick question.
24
+
25
+ ## Why This Matters
26
+
27
+ 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.
28
+
29
+ ```bash
30
+ # 1. Create a ticket
31
+ vibe new "Add user authentication" --assignee <username> --priority high -n
32
+
33
+ # 2. Start working (creates git branch feature/TKT-XXX-slug)
34
+ vibe start TKT-001
35
+
36
+ # 3. Implement the work, commit with ticket reference
37
+ git commit -m "TKT-001: add login endpoint"
38
+
39
+ # 4. Close when done
40
+ vibe close TKT-001
41
+ ```
42
+
43
+ ## Installation
44
+
45
+ ```bash
46
+ npm install -g @vibedx/vibekit
47
+ ```
48
+
49
+ Then in any project:
50
+ ```bash
51
+ vibe init # Creates .vibe/ directory with config, team, templates
52
+ ```
53
+
54
+ ## Core Commands
55
+
56
+ | Command | Purpose |
57
+ |---------|---------|
58
+ | `vibe init` | Initialize vibekit in a project |
59
+ | `vibe new "title"` | Create a ticket |
60
+ | `vibe list` | List all tickets |
61
+ | `vibe start <id>` | Start work (creates git branch) |
62
+ | `vibe start <id> --worktree` | Start work in a separate worktree |
63
+ | `vibe start <id> --agent` | Spawn a Claude agent to work on the ticket |
64
+ | `vibe start <id> <id2> -w --agent` | Spawn agents in parallel worktrees |
65
+ | `vibe status` | Show active worktrees and ticket progress |
66
+ | `vibe pr` | Open a GitHub PR from the current ticket branch |
67
+ | `vibe pr --all` | Open PRs for all worktree branches |
68
+ | `vibe close <id>` | Mark ticket done (cleans up worktree if any) |
69
+ | `vibe lint` | Validate ticket format |
70
+ | `vibe lint --fix` | Auto-fix missing sections |
71
+ | `vibe refine <id>` | AI-enhance ticket details |
72
+ | `vibe plan to-ticket <file>` | Convert a saved plan into tickets (AI) |
73
+ | `vibe swarm` | Spawn parallel agents across open tickets in worktrees |
74
+ | `vibe team` | Manage team members |
75
+
76
+ ## Creating Tickets (for AI agents)
77
+
78
+ **Always use `-n` / `--no-interactive` when creating tickets programmatically.** This skips the AI enhancement prompt which would otherwise block automation.
79
+
80
+ ```bash
81
+ vibe new "Fix login redirect loop" --assignee alice --priority high -n
82
+ vibe new "Add dark mode" --assignee bob --author alice -n
83
+ ```
84
+
85
+ ### Useful flags
86
+
87
+ - `--priority low|medium|high|critical` (default: medium)
88
+ - `--status open|in_progress|review|done` (default: open)
89
+ - `--assignee <username>` — who works on it
90
+ - `--author <username>` — who created it
91
+ - `-d` / `--description "text"` — pre-fill the Description section
92
+ - `--acceptance-criteria "- [ ] criterion 1\n- [ ] criterion 2"` — pre-fill Acceptance Criteria
93
+ - `-n` / `--no-interactive` — skip AI enhancement prompt
94
+
95
+ **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.
96
+
97
+ ## Ticket Structure
98
+
99
+ Tickets live in `.vibe/tickets/` as markdown files with YAML frontmatter:
100
+
101
+ ```markdown
102
+ ---
103
+ id: TKT-001
104
+ title: Add user authentication
105
+ slug: TKT-001-add-user-authentication
106
+ status: open
107
+ priority: high
108
+ assignee: "alice"
109
+ author: "bob"
110
+ created_at: 2026-04-11T10:00:00Z
111
+ updated_at: 2026-04-11T10:00:00Z
112
+ ---
113
+
114
+ ## Description
115
+ What needs to be done and why.
116
+
117
+ ## Acceptance Criteria
118
+ - [ ] Concrete checkbox 1
119
+ - [ ] Concrete checkbox 2
120
+
121
+ ## Implementation Notes
122
+ Technical details, file paths, API references.
123
+
124
+ ## Testing & Test Cases
125
+ Brief test scenarios.
126
+ ```
127
+
128
+ ## Filtering Tickets
129
+
130
+ ```bash
131
+ vibe list # All tickets
132
+ vibe list --status=open # Only open
133
+ vibe list --assignee=alice # Only alice's tickets
134
+ ```
135
+
136
+ ## Team Management
137
+
138
+ Teams are stored in `.vibe/team.yml`. Assignee values in tickets should match team member IDs.
139
+
140
+ ```bash
141
+ vibe team add alice --name "Alice" --github alice --slack U0ABC123 --role Engineer
142
+ vibe team # List members
143
+ vibe team show alice # Show one member
144
+ ```
145
+
146
+ ## When to Use This Skill
147
+
148
+ Apply vibekit workflow when:
149
+
150
+ - User asks to "add a feature", "fix a bug", "implement X", "build Y"
151
+ - Task is non-trivial (more than a one-line fix)
152
+ - Work touches multiple files or requires planning
153
+ - User mentions `vibe`, tickets, tracking, or task management
154
+ - Working in a project that has a `.vibe/` directory
155
+
156
+ **Don't force tickets for trivial changes** — typo fixes, config tweaks, or single-line edits can skip the ticket workflow.
157
+
158
+ ## Integration with Git
159
+
160
+ `vibe start TKT-001` automatically:
161
+ 1. Creates branch `feature/TKT-001-<slug>` (or configured prefix)
162
+ 2. Updates ticket status to `in_progress`
163
+ 3. Switches to the new branch
164
+
165
+ `vibe close TKT-001`:
166
+ 1. Updates ticket status to `done`
167
+ 2. Leaves the branch for manual merge/PR
168
+
169
+ ### Worktree Support (Parallel Development)
170
+
171
+ Use `--worktree` / `-w` to work on multiple tickets simultaneously without switching branches:
172
+
173
+ ```bash
174
+ # Start ticket in a dedicated worktree
175
+ vibe start TKT-002 --worktree
176
+
177
+ # The worktree is created at ~/.vibekit/worktrees/<repo>/<branch>/
178
+ # Your main working directory stays on its current branch
179
+ # cd into the worktree path to work on the ticket
180
+
181
+ # Close automatically removes the worktree
182
+ vibe close TKT-002
183
+
184
+ # If the worktree has uncommitted changes, use --force
185
+ vibe close TKT-002 --force
186
+ ```
187
+
188
+ `vibe list` shows a 🌿 indicator next to tickets with active worktrees.
189
+
190
+ ### Spawning Claude Agents
191
+
192
+ Use `--agent` to spawn a Claude Code agent that autonomously works on a ticket:
193
+
194
+ ```bash
195
+ # Single ticket — agent works in the current directory
196
+ vibe start TKT-003 --agent
197
+
198
+ # Multiple tickets — each gets its own worktree + agent
199
+ vibe start TKT-003 TKT-004 TKT-005 -w --agent
200
+ ```
201
+
202
+ Agents automatically:
203
+ - Read the ticket requirements and implement the work
204
+ - Commit changes with ticket references
205
+ - Mark the ticket as `done` when complete (or `in_progress` if further changes needed)
206
+ - Have full tool access (git, file I/O, CLI)
207
+ - Receive the vibekit skill context so they know how to use vibe commands
208
+
209
+ Agent timeout defaults to 15 minutes (900s). Configure in `.vibe/config.yml`:
210
+
211
+ ```yaml
212
+ worktree:
213
+ agent:
214
+ timeout: 900 # seconds
215
+ ```
216
+
217
+ ### Opening Pull Requests
218
+
219
+ Use `vibe pr` to open GitHub PRs from ticket branches:
220
+
221
+ ```bash
222
+ # PR for the current branch
223
+ vibe pr
224
+
225
+ # PRs for specific tickets
226
+ vibe pr TKT-003 TKT-004
227
+
228
+ # PRs for all worktree branches
229
+ vibe pr --all
230
+
231
+ # Draft PR
232
+ vibe pr --draft
233
+ ```
234
+
235
+ PR title and body are auto-populated from ticket content. Ticket status is set to `review`.
236
+
237
+ ### Plans → Tickets
238
+
239
+ When you (Claude) produce an implementation plan, save it to `.vibe/plans/` as a
240
+ markdown file, then turn it into tickets:
241
+
242
+ ```bash
243
+ # Preview the tickets vibekit would extract from a plan (no files written)
244
+ vibe plan to-ticket .vibe/plans/my-feature.md
245
+
246
+ # Create the tickets once the breakdown looks right
247
+ vibe plan to-ticket .vibe/plans/my-feature.md --auto
248
+
249
+ # Dry-run shows the extracted items without creating anything
250
+ vibe plan to-ticket .vibe/plans/my-feature.md --dry-run
251
+ ```
252
+
253
+ The command sends the plan to Claude, which extracts discrete work items
254
+ (title, description, acceptance criteria, priority, estimate) and writes one
255
+ ticket per item to `.vibe/tickets/`. Default is preview-then-confirm: it shows
256
+ the breakdown and only writes files when you pass `--auto`. Chain it with
257
+ `vibe start TKT-XXX` to begin work.
258
+
259
+ ### Swarming (Parallel Agents)
260
+
261
+ `vibe swarm` spins up multiple Claude agents at once, each in its own worktree,
262
+ to burn down a batch of tickets in parallel:
263
+
264
+ ```bash
265
+ # Swarm all open tickets (capped by config swarm.maxAgents, default 3)
266
+ vibe swarm
267
+
268
+ # Limit the number of concurrent agents
269
+ vibe swarm --count 5
270
+
271
+ # Only swarm tickets matching a filter (frontmatter key:value)
272
+ vibe swarm --filter priority:high
273
+
274
+ # Use a specific base branch for the worktrees
275
+ vibe swarm --base main
276
+
277
+ # Check on a running swarm
278
+ vibe swarm status
279
+ ```
280
+
281
+ Configure caps and timeout in `.vibe/config.yml`:
282
+
283
+ ```yaml
284
+ swarm:
285
+ maxAgents: 3
286
+ timeout: 900 # seconds
287
+ ```
288
+
289
+ ### Monitoring Progress
290
+
291
+ ```bash
292
+ # Show active worktrees and agent status
293
+ vibe status
294
+
295
+ # List in-progress tickets
296
+ vibe list --status=in_progress
297
+ ```
298
+
299
+ ## Automation Pattern
300
+
301
+ For bots and automated agents working through tickets:
302
+
303
+ ```bash
304
+ # Find open tickets assigned to you
305
+ vibe list --assignee=mybotname --status=open
306
+
307
+ # For each ticket:
308
+ # 1. Read .vibe/tickets/TKT-XXX-*.md for full context
309
+ # 2. Do the work on branch feature/<ticket-id>-<slug>
310
+ # 3. Commit changes
311
+ # 4. Open PR: vibe pr
312
+ # 5. Close: vibe close TKT-XXX
313
+ ```
314
+
315
+ ## Links
316
+
317
+ - Repo: https://github.com/vibedx/vibekit
318
+ - npm: https://www.npmjs.com/package/@vibedx/vibekit
319
+ - Issues: https://github.com/vibedx/vibekit/issues