@crewx/wbs 0.1.4 → 0.1.6

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 (15) hide show
  1. package/README.md +7 -7
  2. package/SKILL.md +1198 -1196
  3. package/package.json +54 -38
  4. package/dist/cli.d.ts +0 -3
  5. package/dist/cli.d.ts.map +0 -1
  6. package/dist/cli.js +0 -721
  7. package/dist/cli.js.map +0 -1
  8. package/dist/src/engine.d.ts +0 -54
  9. package/dist/src/engine.d.ts.map +0 -1
  10. package/dist/src/engine.js +0 -551
  11. package/dist/src/engine.js.map +0 -1
  12. package/dist/src/types.d.ts +0 -60
  13. package/dist/src/types.d.ts.map +0 -1
  14. package/dist/src/types.js +0 -3
  15. package/dist/src/types.js.map +0 -1
package/SKILL.md CHANGED
@@ -1,1196 +1,1198 @@
1
- ---
2
- name: wbs
3
- description: Work Breakdown Structure (WBS) management skill. Enables AI coordinators to decompose complex tasks into 30-minute timeboxed jobs and execute them via worker agents.
4
- version: 0.3.0
5
- ---
6
-
7
- # WBS Skill
8
-
9
- Provides state management and worker execution for Work Breakdown Structure based task decomposition.
10
-
11
- ## Core Principle
12
-
13
- **System provides state management, AI agent makes intelligent decisions.**
14
-
15
- ```
16
- User Request
17
- │
18
- ▼
19
- ┌─────────────────────────────────────────────────────┐
20
- │ Coordinator Agent (with WBS skill) │
21
- │ - Analyze request (AI judgment) │
22
- │ - Decompose into 30-min Jobs (AI judgment) │
23
- │ - Execute workers: crewx x "@agent action" │
24
- │ - Track state: wbs.js │
25
- └─────────────────────────────────────────────────────┘
26
- │
27
- ├──────────────┬──────────────┐
28
- ▼ ▼ ▼
29
- ┌─────────┐ ┌─────────┐ ┌─────────┐
30
- │ Worker1 │ │ Worker2 │ │ Worker3 │
31
- │ @claude │ │ @gemini │ │ @copilot│
32
- └─────────┘ └─────────┘ └─────────┘
33
- ```
34
-
35
- ## What is WBS Skill?
36
-
37
- The WBS (Work Breakdown Structure) skill is a **project management system for complex AI-driven tasks**. It enables coordinator agents to:
38
-
39
- 1. **Decompose complex tasks** into manageable 30-minute jobs
40
- 2. **Track progress** with state management (pending → running → completed/failed)
41
- 3. **Coordinate multiple agents** by assigning different jobs to specialized workers
42
- 4. **Manage context** through detail documents and structured workflow
43
- 5. **Execute in parallel** by distributing jobs across multiple worker agents
44
-
45
- ### Key Characteristics
46
-
47
- - **Structured Approach**: Projects are broken down into jobs with clear status tracking
48
- - **Time-Boxed Execution**: Each job targets 15-45 minutes (optimal: 25-30 min)
49
- - **Multi-Agent Coordination**: Different jobs can be assigned to different AI agents
50
- - **State Persistence**: All project data, jobs, and execution history are tracked in `.wbs-data.json`
51
- - **Automated Workflow**: Git branching, PR templates, and issue tracking integration
52
- - **Job Slug System**: Jobs are identified by intuitive slugs (`wbs-5-1`, `wbs-5-2`) computed from `wbs_id + seq`
53
- - **Auto-generated Detail Files**: `job add` automatically generates/updates `wbs-details/wbs-{N}-detail.md` with job metadata
54
-
55
- ## Job Slug System
56
-
57
- Each job gets a **slug** computed from its WBS ID and sequence number: `wbs-{N}-{seq}`
58
-
59
- | Internal ID | Slug | Meaning |
60
- |------------|------|---------|
61
- | `job-15` | `wbs-5-1` | WBS-5의 1번째 Job |
62
- | `job-16` | `wbs-5-2` | WBS-5의 2번째 Job |
63
- | `job-17` | `wbs-5-3` | WBS-5의 3번째 Job |
64
-
65
- - Slugs are **computed values** (not stored in DB) — derived from `wbs_id` + `seq`
66
- - All commands accepting `<job-id>` also accept `<slug>`: `wbs job update wbs-5-1 --status completed`
67
- - Git branches use slug naming: `feature/wbs-5-1`
68
- - Worktree directories align with slug naming
69
-
70
- ## When to Use WBS Skill
71
-
72
- ### Use WBS When
73
-
74
- Choose WBS for tasks that meet **any** of these criteria:
75
-
76
- - **Complex multi-step tasks** (> 45 minutes total)
77
- - Feature implementations spanning multiple files/modules
78
- - Large-scale refactoring projects
79
- - Bug fix sprints with multiple related issues
80
-
81
- - **30-minute timeboxing needed**
82
- - Tasks prone to context loss (LLM "Lost in the Middle" problem)
83
- - Work requiring periodic checkpoints and validation
84
- - Projects where partial progress needs to be tracked
85
-
86
- - **Parallel execution beneficial**
87
- - Jobs that can be distributed across multiple worker agents
88
- - Tasks where different agents excel at different subtasks
89
- - Work that benefits from concurrent execution
90
-
91
- - **Progress tracking important**
92
- - Team collaboration requiring visibility into task status
93
- - Projects with external stakeholders needing updates
94
- - Work where partial failure recovery is critical
95
-
96
- - **GitHub integration needed**
97
- - Tasks linked to GitHub issues
98
- - Projects requiring structured PR workflows
99
- - Work following standardized git branching strategies
100
-
101
- ### Use Direct Delegation When
102
-
103
- Skip WBS for simpler scenarios:
104
-
105
- - Single-step tasks (< 15 minutes)
106
- - One-off file modifications
107
- - Quick code analysis or queries
108
- - Rapid prototyping without tracking needs
109
- - Tasks with no need for state persistence
110
-
111
- ### Decision Flow
112
-
113
- ```
114
- Task received
115
- │
116
- ▼
117
- Expected duration?
118
- │
119
- ├─── < 15 min ──────────────────────► Direct Delegation
120
- │
121
- ├─── 15-45 min ─┬─ Single step ──────► Direct Delegation
122
- │ └─ Multi-step ────────► WBS Skill
123
- │
124
- └─── > 45 min ──────────────────────► WBS Skill (required)
125
- ```
126
-
127
- ## Use Case Examples
128
-
129
- ### 1. Complex Feature Implementation
130
-
131
- **Scenario**: Implement user authentication system
132
-
133
- ```bash
134
- # WBS approach - structured and tracked
135
- wbs.js create "User Authentication Implementation"
136
- wbs.js job add wbs-1 --title "Design User model" --agent "@claude:sonnet" --seq 1
137
- wbs.js job add wbs-1 --title "Implement login API" --agent "@copilot" --seq 2
138
- wbs.js job add wbs-1 --title "Add JWT handling" --agent "@copilot" --seq 3
139
- wbs.js job add wbs-1 --title "Write unit tests" --agent "@claude:sonnet" --seq 4
140
- wbs.js job run wbs-1
141
- ```
142
-
143
- **Why WBS**: Multi-step process, multiple agents, progress tracking needed
144
-
145
- ### 2. Bug Fix Sprint
146
-
147
- **Scenario**: Fix multiple related authentication bugs
148
-
149
- ```bash
150
- # WBS approach - organized issue resolution
151
- wbs.js create "Bug Fix Sprint"
152
- wbs.js job add wbs-2 --title "Fix login bug" --agent "@claude" --issue 42 --seq 1
153
- wbs.js job add wbs-2 --title "Fix session timeout" --agent "@claude" --issue 43 --seq 2
154
- wbs.js job add wbs-2 --title "Fix password reset" --agent "@claude" --issue 44 --seq 3
155
- wbs.js job run wbs-2
156
- ```
157
-
158
- **Why WBS**: Multiple issues, GitHub integration, failure recovery important
159
-
160
- ### 3. Large Refactoring
161
-
162
- **Scenario**: Refactor API layer across multiple modules
163
-
164
- ```bash
165
- # WBS approach - context preservation across modules
166
- wbs.js create "API Refactoring"
167
- wbs.js job add wbs-3 --title "Refactor auth module" --agent "@claude" --seq 1
168
- wbs.js job add wbs-3 --title "Refactor user module" --agent "@claude" --seq 2
169
- wbs.js job add wbs-3 --title "Update tests" --agent "@copilot" --seq 3
170
- wbs.js job run wbs-3
171
- ```
172
-
173
- **Why WBS**: Context preservation critical, step-by-step validation needed
174
-
175
- ### 4. Simple Code Fix (No WBS)
176
-
177
- **Scenario**: Fix a typo in documentation
178
-
179
- ```bash
180
- # Direct delegation - immediate execution
181
- crewx x "@claude Fix typo in README.md line 42"
182
- ```
183
-
184
- **Why Direct**: Single-step, < 15 minutes, no tracking needed
185
-
186
- ## 30-Minute Timeboxing
187
-
188
- | Category | Time | Description |
189
- |----------|------|-------------|
190
- | Minimum | 15 min | Below this → don't separate as Job |
191
- | Optimal | 25-30 min | Target duration |
192
- | Maximum | 45 min | Above this → re-decompose |
193
-
194
- **Rationale**: LLM context limits (Lost in the Middle, Context Rot) + Pomodoro Technique
195
-
196
- ## ⚠️ Job Description Template (MANDATORY)
197
-
198
- **모든 Job은 반드시 아래 템플릿을 따라야 합니다.** 모호한 Job Description은 미완성 작업의 주요 원인입니다.
199
-
200
- ### 템플릿
201
-
202
- ```markdown
203
- **산출물 (Deliverables):**
204
- 1. path/to/file1.tsx - 설명
205
- 2. path/to/file2.ts - 설명
206
- 3. 기존 파일 수정: path/to/existing.tsx
207
-
208
- **완료 기준 (Done Criteria):**
209
- - [ ] 컴포넌트 렌더링 확인
210
- - [ ] Store 연동 동작 확인
211
- - [ ] 라우트 추가 및 네비게이션 확인
212
-
213
- **참고 문서:**
214
- - docs/ui-screens/screens/XX.md
215
- - 와이어프레임/디자인 링크
216
- ```
217
-
218
- ### 사용 예시
219
-
220
- ```bash
221
- # ❌ BAD - 모호한 Job Description
222
- node wbs.js job add wbs-1 \
223
- --title "에이전트 설정 화면" \
224
- --desc "crewx.yaml 에이전트 목록 표시. 모델/프로바이더/프롬프트 편집 UI." \
225
- --agent "@launcher_gemini_dev"
226
-
227
- # ✅ GOOD - 명확한 산출물과 완료 기준
228
- node wbs.js job add wbs-1 \
229
- --title "에이전트 설정 화면" \
230
- --desc "**산출물:**
231
- 1. src/renderer/components/AgentConfig/AgentConfigPage.tsx - 에이전트 목록 페이지
232
- 2. src/renderer/components/AgentConfig/AgentEditModal.tsx - 편집 모달
233
- 3. src/renderer/App.tsx - /agents 라우트 추가
234
- 4. src/renderer/components/Layout/Sidebar.tsx - 메뉴 추가
235
-
236
- **완료 기준:**
237
- - [ ] /agents 경로 접근 시 에이전트 목록 표시
238
- - [ ] 편집 버튼 클릭 시 모달 열림
239
- - [ ] 저장 시 crewx.yaml 반영
240
-
241
- **참고:** docs/ui-screens/screens/03-agent.md" \
242
- --agent "@launcher_gemini_dev"
243
- ```
244
-
245
- ### 왜 필수인가?
246
-
247
- | 문제 | 모호한 Job Description | 템플릿 사용 시 |
248
- |------|----------------------|---------------|
249
- | **범위 해석** | 에이전트가 임의로 해석 | 명확한 파일 목록 |
250
- | **완료 판단** | 수동으로 "완료" 처리 | 체크리스트 검증 |
251
- | **누락 방지** | UI 없이 Store만 구현 | 모든 산출물 명시 |
252
- | **리뷰 용이** | 뭘 확인해야 하는지 불명확 | 체크리스트 기반 리뷰 |
253
-
254
- ### 통합 테스트 Job 템플릿
255
-
256
- 통합 테스트 Job은 특별히 검증 항목을 상세히 명시해야 합니다:
257
-
258
- ```bash
259
- node wbs.js job add wbs-1 \
260
- --title "통합 테스트" \
261
- --desc "**검증 시나리오:**
262
- 1. 온보딩 → 프리셋 선택 → 설치 완료
263
- 2. 대시보드 → 에이전트 목록 표시
264
- 3. 에이전트 설정 → 편집 → 저장
265
-
266
- **검증 방법:**
267
- - [ ] 각 시나리오 수동 실행
268
- - [ ] 스크린샷 캡처 (skills/playwright-python 사용)
269
- - [ ] 에러 로그 확인
270
-
271
- **통과 기준:**
272
- - 모든 시나리오 정상 동작
273
- - 콘솔 에러 없음" \
274
- --agent "@launcher_codex_dev"
275
- ```
276
-
277
- ## Installation
278
-
279
- ```bash
280
- cd skills/wbs
281
- npm install
282
- ```
283
-
284
- Requires Node.js 16+.
285
-
286
- ## Commands Reference
287
-
288
- ### Project Management Commands
289
-
290
- | Command | Syntax | Description |
291
- |---------|--------|-------------|
292
- | **create** | `wbs.js create "Title" [--detail path]` | Create new WBS project with sequential ID (wbs-1, wbs-2, ...) |
293
- | **list** | `wbs.js list [--json]` | List all projects with status and progress |
294
- | **status** | `wbs.js status <wbs-id> [--json]` | Get detailed project info including all jobs and summary stats |
295
- | **delete** | `wbs.js delete <wbs-id>` | Delete project and all associated jobs/executions (irreversible) |
296
-
297
- ### Job Management Commands
298
-
299
- | Command | Syntax | Description |
300
- |---------|--------|-------------|
301
- | **job add** | `wbs.js job add <wbs-id> --title "Title" --agent "@agent" [options]` | Add new job to project. Options: `--desc`, `--seq`, `--issue` |
302
- | **job list** | `wbs.js job list <wbs-id> [--json]` | List all jobs ordered by sequence number |
303
- | **job update** | `wbs.js job update <job-id\|slug> [options]` | Update job properties. Options: `--status`, `--title`, `--desc`, `--agent`, `--seq`, `--issue` |
304
- | **job run** | `wbs.js job run <wbs-id>` | Execute all pending jobs sequentially (30-min timeout each) |
305
- | **job next** | `wbs.js job next <wbs-id>` | Execute only the next pending job (manual step-by-step) |
306
- | **job retry** | `wbs.js job retry <job-id\|slug>` | Retry a failed or completed job |
307
-
308
- ### Execution Management Commands
309
-
310
- | Command | Syntax | Description |
311
- |---------|--------|-------------|
312
- | **exec list** | `wbs.js exec list <job-id\|slug> [--json]` | List execution history for a job |
313
- | **exec status** | `wbs.js exec status <exec-id> [--json]` | Get detailed execution info |
314
- | **exec kill** | `wbs.js exec kill <exec-id>` | Kill a running execution |
315
- | **exec running** | `wbs.js exec running [--json]` | List all currently running executions |
316
-
317
- ### Coordinator Commands (Natural Language)
318
-
319
- | Command | Syntax | Description |
320
- |---------|--------|-------------|
321
- | **q** | `wbs.js q "질문"` | Ask coordinator a question (via `@wbs_coordinator`) |
322
- | **x** | `wbs.js x "요청"` | Request coordinator to execute an action |
323
-
324
- ### Daemon Commands (Background Scheduler)
325
-
326
- | Command | Syntax | Description |
327
- |---------|--------|-------------|
328
- | **daemon start** | `wbs.js daemon start` | Start background scheduler |
329
- | **daemon stop** | `wbs.js daemon stop` | Stop running daemon |
330
- | **daemon status** | `wbs.js daemon status` | Check daemon status |
331
- | **daemon tick** | `wbs.js daemon tick` | Manual tick for testing |
332
-
333
- ### Common Usage Patterns
334
-
335
- ```bash
336
- # Create and run a complete project
337
- wbs.js create "User Authentication"
338
- wbs.js job add wbs-1 --title "Design schema" --agent "@claude:sonnet" --seq 1
339
- wbs.js job add wbs-1 --title "Implement API" --agent "@copilot" --seq 2
340
- wbs.js job add wbs-1 --title "Write tests" --agent "@claude:sonnet" --seq 3
341
- wbs.js job run wbs-1
342
-
343
- # Check progress
344
- wbs.js status wbs-1
345
-
346
- # Handle failures (use job-id or slug)
347
- wbs.js job list wbs-1 --json | jq '.[] | select(.status=="failed")'
348
- wbs.js job retry wbs-1-3 # by slug
349
- wbs.js job retry job-5 # by job-id
350
-
351
- # Issue-based workflow
352
- wbs.js job add wbs-2 --title "Fix bug" --agent "@claude" --issue 42
353
- ```
354
-
355
- ### Output Formats
356
-
357
- - **Default**: Human-readable tables with emoji status icons
358
- - **--json**: Machine-parseable JSON for scripting and automation
359
-
360
- For detailed command documentation, see:
361
- - [COMMANDS.md](./COMMANDS.md) - Complete project commands reference
362
- - [job-management.md](./job-management.md) - Comprehensive job management guide
363
-
364
- ## Practical Usage Examples
365
-
366
- This section provides comprehensive real-world examples of using the WBS skill effectively.
367
-
368
- ### Example 1: Simple Workflow (Create → Add Jobs → Run)
369
-
370
- The most basic WBS workflow involves creating a project, adding jobs, and running them sequentially.
371
-
372
- **Scenario**: Build a simple REST API for a todo application
373
-
374
- ```bash
375
- # 1. Create the project
376
- node wbs.js create "Todo REST API"
377
- ```
378
-
379
- **Expected output:**
380
- ```json
381
- {
382
- "id": "wbs-1",
383
- "title": "Todo REST API",
384
- "status": "planning",
385
- "detailPath": "skills/wbs/details/wbs-1-detail.md",
386
- "created_at": "2025-12-18T08:00:00.000Z"
387
- }
388
- ```
389
-
390
- ```bash
391
- # 2. Add jobs for implementation
392
- node wbs.js job add wbs-1 \
393
- --title "Design database schema" \
394
- --agent "@claude:sonnet" \
395
- --seq 1 \
396
- --desc "Create SQLite schema for todos table with id, title, completed, created_at fields"
397
-
398
- node wbs.js job add wbs-1 \
399
- --title "Implement CRUD endpoints" \
400
- --agent "@copilot" \
401
- --seq 2 \
402
- --desc "Create Express routes: GET /todos, POST /todos, PUT /todos/:id, DELETE /todos/:id"
403
-
404
- node wbs.js job add wbs-1 \
405
- --title "Add input validation" \
406
- --agent "@claude:sonnet" \
407
- --seq 3 \
408
- --desc "Implement request validation middleware using express-validator"
409
-
410
- node wbs.js job add wbs-1 \
411
- --title "Write integration tests" \
412
- --agent "@copilot" \
413
- --seq 4 \
414
- --desc "Create test suite covering all CRUD operations using supertest"
415
- ```
416
-
417
- ```bash
418
- # 3. Review the planned jobs
419
- node wbs.js status wbs-1
420
- ```
421
-
422
- **Expected output:**
423
- ```
424
- 📋 Todo REST API (wbs-1)
425
- Status: planning | Progress: 0% (0/4)
426
- Detail: skills/wbs/details/wbs-1-detail.md
427
-
428
- Jobs:
429
- | 상태 | # | Slug | ID | 작업명 | 담당 |
430
- |------|----|-----------|-------|--------------------------|-----------------|
431
- | ⬜️ | 1 | wbs-1-1 | job-1 | Design database schema | @claude:sonnet |
432
- | ⬜️ | 2 | wbs-1-2 | job-2 | Implement CRUD endpoints | @copilot |
433
- | ⬜️ | 3 | wbs-1-3 | job-3 | Add input validation | @claude:sonnet |
434
- | ⬜️ | 4 | wbs-1-4 | job-4 | Write integration tests | @copilot |
435
- ```
436
-
437
- ```bash
438
- # 4. Run all jobs
439
- node wbs.js job run wbs-1
440
- ```
441
-
442
- **Expected output:**
443
- ```
444
- ══════════════════════════════════════════════════
445
- [WBS] Starting project: Todo REST API
446
- ══════════════════════════════════════════════════
447
-
448
- [WBS] Running job: Design database schema
449
- [WBS] Agent: @claude:sonnet
450
- [WBS] Description: Create SQLite schema for todos table...
451
- [WBS] Timeout: 30 minutes
452
- ──────────────────────────────────────────────────
453
- [Agent executes and produces output...]
454
- ──────────────────────────────────────────────────
455
- [WBS] Job completed: Design database schema
456
-
457
- [WBS] Running job: Implement CRUD endpoints
458
- [WBS] Agent: @copilot
459
- [WBS] Timeout: 30 minutes
460
- ──────────────────────────────────────────────────
461
- [Agent executes and produces output...]
462
- ──────────────────────────────────────────────────
463
- [WBS] Job completed: Implement CRUD endpoints
464
-
465
- [... continues for remaining jobs ...]
466
-
467
- ══════════════════════════════════════════════════
468
- [WBS] Project completed: Todo REST API
469
- [WBS] Completed: 4, Failed: 0
470
- ══════════════════════════════════════════════════
471
- ```
472
-
473
- ```bash
474
- # 5. Verify completion
475
- node wbs.js status wbs-1
476
- ```
477
-
478
- **Final output:**
479
- ```
480
- 📋 Todo REST API (wbs-1)
481
- Status: completed | Progress: 100% (4/4)
482
- Detail: skills/wbs/details/wbs-1-detail.md
483
-
484
- Jobs:
485
- | 상태 | # | Slug | ID | 작업명 | 담당 | Status |
486
- |------|----|-----------|-------|--------------------------|-----------------|-----------|
487
- | ✅ | 1 | wbs-1-1 | job-1 | Design database schema | @claude:sonnet | completed |
488
- | ✅ | 2 | wbs-1-2 | job-2 | Implement CRUD endpoints | @copilot | completed |
489
- | ✅ | 3 | wbs-1-3 | job-3 | Add input validation | @claude:sonnet | completed |
490
- | ✅ | 4 | wbs-1-4 | job-4 | Write integration tests | @copilot | completed |
491
- ```
492
-
493
- ---
494
-
495
- ### Example 2: Issue-Based Workflow
496
-
497
- Use WBS to manage multiple GitHub issues systematically.
498
-
499
- **Scenario**: Fix authentication-related bugs tracked in GitHub
500
-
501
- ```bash
502
- # 1. Create project for bug fixes
503
- node wbs.js create "Authentication Bug Fixes"
504
- ```
505
-
506
- **Output:**
507
- ```json
508
- {
509
- "id": "wbs-2",
510
- "title": "Authentication Bug Fixes",
511
- "status": "planning"
512
- }
513
- ```
514
-
515
- ```bash
516
- # 2. Add jobs linked to GitHub issues
517
- node wbs.js job add wbs-2 \
518
- --title "Fix: Login fails with special characters in password" \
519
- --agent "@claude:sonnet" \
520
- --issue 123 \
521
- --seq 1
522
-
523
- node wbs.js job add wbs-2 \
524
- --title "Fix: Session timeout not working" \
525
- --agent "@claude:sonnet" \
526
- --issue 124 \
527
- --seq 2
528
-
529
- node wbs.js job add wbs-2 \
530
- --title "Fix: Password reset email not sent" \
531
- --agent "@claude:sonnet" \
532
- --issue 125 \
533
- --seq 3
534
- ```
535
-
536
- **What happens during execution:**
537
-
538
- When you run `node wbs.js job run wbs-2`, each job receives these instructions:
539
-
540
- ```
541
- ## 작업 지시
542
- GitHub Issue #123를 처리하세요.
543
-
544
- **당신의 기존 개발 프로세스를 따르세요:**
545
- 1. `gh issue view 123`로 이슈 확인
546
- 2. 브랜치 생성 및 작업
547
- 3. PR 생성
548
- 4. 이슈에 결과 코멘트
549
-
550
- WBS 추적 정보:
551
- - WBS: wbs-2
552
- - Job: job-1
553
- ```
554
-
555
- **Advantages:**
556
- - Automatic issue-branch-PR linking
557
- - Agent follows its own development workflow
558
- - Easy progress tracking via GitHub
559
- - Issue comments document resolution
560
-
561
- ---
562
-
563
- ### Example 3: Step-by-Step Execution
564
-
565
- Execute jobs manually one at a time with review between each step.
566
-
567
- **Scenario**: Refactoring legacy code where each step needs verification
568
-
569
- ```bash
570
- # 1. Create project
571
- node wbs.js create "Legacy Code Refactoring"
572
-
573
- # 2. Add jobs
574
- node wbs.js job add wbs-3 \
575
- --title "Extract UserService from monolithic controller" \
576
- --agent "@claude:opus" \
577
- --seq 1 \
578
- --desc "Move user-related logic from AppController to new UserService class"
579
-
580
- node wbs.js job add wbs-3 \
581
- --title "Add dependency injection" \
582
- --agent "@claude:sonnet" \
583
- --seq 2 \
584
- --desc "Refactor UserService to use constructor injection for database"
585
-
586
- node wbs.js job add wbs-3 \
587
- --title "Update unit tests" \
588
- --agent "@copilot" \
589
- --seq 3 \
590
- --desc "Modify tests to work with new UserService architecture"
591
-
592
- node wbs.js job add wbs-3 \
593
- --title "Verify integration tests pass" \
594
- --agent "@copilot" \
595
- --seq 4 \
596
- --desc "Run full test suite and fix any integration issues"
597
- ```
598
-
599
- ```bash
600
- # 3. Execute first job only
601
- node wbs.js job next wbs-3
602
- ```
603
-
604
- **Output:**
605
- ```
606
- [WBS] Running job: Extract UserService from monolithic controller
607
- [WBS] Agent: @claude:opus
608
- [WBS] Timeout: 30 minutes
609
- ──────────────────────────────────────────────────
610
- [Agent output...]
611
- ──────────────────────────────────────────────────
612
- [WBS] Job completed: Extract UserService from monolithic controller
613
-
614
- {
615
- "success": true,
616
- "execId": "exec-1"
617
- }
618
- ```
619
-
620
- ```bash
621
- # 4. Review changes before continuing
622
- git diff
623
- npm test
624
-
625
- # 5. If satisfied, run next job
626
- node wbs.js job next wbs-3
627
- ```
628
-
629
- **Output:**
630
- ```
631
- [WBS] Running job: Add dependency injection
632
- [WBS] Agent: @claude:sonnet
633
- ...
634
- ```
635
-
636
- ```bash
637
- # 6. Continue step by step
638
- node wbs.js status wbs-3 # Check progress
639
- node wbs.js job next wbs-3 # Run next job
640
- ```
641
-
642
- **Use cases for step-by-step execution:**
643
- - Code reviews between steps
644
- - Testing after each change
645
- - Learning/understanding the codebase
646
- - High-risk refactoring
647
- - Debugging job configurations
648
-
649
- ---
650
-
651
- ### Example 4: Handling Failures
652
-
653
- Recover from failed jobs and retry with updated configurations.
654
-
655
- **Scenario**: API implementation where initial attempts fail
656
-
657
- ```bash
658
- # 1. Create project and add jobs
659
- node wbs.js create "Payment API Integration"
660
-
661
- node wbs.js job add wbs-4 \
662
- --title "Integrate Stripe SDK" \
663
- --agent "@copilot" \
664
- --seq 1
665
-
666
- node wbs.js job add wbs-4 \
667
- --title "Implement payment endpoint" \
668
- --agent "@claude:sonnet" \
669
- --seq 2
670
-
671
- node wbs.js job add wbs-4 \
672
- --title "Add webhook handler" \
673
- --agent "@claude:sonnet" \
674
- --seq 3
675
-
676
- # 2. Run all jobs
677
- node wbs.js job run wbs-4
678
- ```
679
-
680
- **Suppose job-2 fails:**
681
-
682
- ```
683
- [WBS] Running job: Implement payment endpoint
684
- [WBS] Agent: @claude:sonnet
685
- ──────────────────────────────────────────────────
686
- Error: Missing API key configuration
687
- ──────────────────────────────────────────────────
688
- [WBS] Job failed: Implement payment endpoint
689
- ```
690
-
691
- ```bash
692
- # 3. Check which jobs failed
693
- node wbs.js job list wbs-4 --json | jq '.[] | select(.status=="failed")'
694
- ```
695
-
696
- **Output:**
697
- ```json
698
- {
699
- "id": "job-2",
700
- "wbs_id": "wbs-4",
701
- "title": "Implement payment endpoint",
702
- "status": "failed",
703
- "agent": "@claude:sonnet",
704
- "seq": 2
705
- }
706
- ```
707
-
708
- ```bash
709
- # 4. Review execution history
710
- node wbs.js exec list job-2
711
- ```
712
-
713
- **Output:**
714
- ```
715
- 📋 Executions for job-2
716
-
717
- | 상태 | ID | PID | 시작 | 종료 | 코드 |
718
- |------|---------|-------|---------------------|---------------------|------|
719
- | ❌ | exec-2 | 45678 | 2025-12-18 09:15:00 | 2025-12-18 09:18:00 | 1 |
720
- ```
721
-
722
- ```bash
723
- # 5. Fix the issue (add environment variable or update job description)
724
- node wbs.js job update job-2 \
725
- --desc "Implement payment endpoint. Use STRIPE_API_KEY from .env file. Handle both test and production modes."
726
-
727
- # 6. Retry the failed job
728
- node wbs.js job retry job-2
729
- ```
730
-
731
- **Output:**
732
- ```
733
- [WBS] Retrying job: Implement payment endpoint
734
- [WBS] Running job: Implement payment endpoint
735
- [WBS] Agent: @claude:sonnet
736
- [WBS] Timeout: 30 minutes
737
- ──────────────────────────────────────────────────
738
- [Agent output...]
739
- ──────────────────────────────────────────────────
740
- [WBS] Job completed: Implement payment endpoint
741
-
742
- {
743
- "success": true,
744
- "execId": "exec-5"
745
- }
746
- ```
747
-
748
- ```bash
749
- # 7. Continue with remaining jobs
750
- node wbs.js job run wbs-4
751
- ```
752
-
753
- **Final status:**
754
- ```
755
- 📋 Payment API Integration (wbs-4)
756
- Status: completed | Progress: 100% (3/3)
757
-
758
- Jobs:
759
- | 상태 | # | ID | 작업명 | Status |
760
- |------|----|----|--------------------------|-----------|
761
- | ✅ | 1 | job-1 | Integrate Stripe SDK | completed |
762
- | ✅ | 2 | job-2 | Implement payment endpoint| completed |
763
- | ✅ | 3 | job-3 | Add webhook handler | completed |
764
- ```
765
-
766
- **Batch retry all failed jobs:**
767
- ```bash
768
- # Find and retry all failed jobs in a project
769
- for job in $(node wbs.js job list wbs-4 --json | jq -r '.[] | select(.status=="failed") | .id'); do
770
- echo "Retrying $job..."
771
- node wbs.js job retry $job
772
- done
773
- ```
774
-
775
- ---
776
-
777
- ### Example 5: Complex Multi-Agent Coordination
778
-
779
- Distribute work across different AI agents based on their strengths.
780
-
781
- **Scenario**: Build a full-stack feature with frontend, backend, and tests
782
-
783
- ```bash
784
- # 1. Create project
785
- node wbs.js create "User Profile Feature"
786
-
787
- # 2. Add jobs with appropriate agent selection
788
- # Backend work - @claude:sonnet for complex logic
789
- node wbs.js job add wbs-5 \
790
- --title "Design User Profile data model" \
791
- --agent "@claude:sonnet" \
792
- --seq 1 \
793
- --desc "Create schema with fields: avatar, bio, social_links, preferences"
794
-
795
- # Implementation - @copilot for straightforward coding
796
- node wbs.js job add wbs-5 \
797
- --title "Implement profile CRUD API" \
798
- --agent "@copilot" \
799
- --seq 2 \
800
- --desc "REST endpoints for profile operations with validation"
801
-
802
- # Complex architecture - @claude:opus for advanced decisions
803
- node wbs.js job add wbs-5 \
804
- --title "Design avatar upload system" \
805
- --agent "@claude:opus" \
806
- --seq 3 \
807
- --desc "S3 integration with image processing, CDN, and caching strategy"
808
-
809
- # Implementation again
810
- node wbs.js job add wbs-5 \
811
- --title "Implement avatar upload" \
812
- --agent "@copilot" \
813
- --seq 4 \
814
- --desc "File upload endpoint with S3 SDK and image optimization"
815
-
816
- # Frontend - @claude:sonnet for React components
817
- node wbs.js job add wbs-5 \
818
- --title "Create profile edit form" \
819
- --agent "@claude:sonnet" \
820
- --seq 5 \
821
- --desc "React component with form validation and avatar preview"
822
-
823
- # Testing - @copilot excels at test generation
824
- node wbs.js job add wbs-5 \
825
- --title "Write comprehensive tests" \
826
- --agent "@copilot" \
827
- --seq 6 \
828
- --desc "Unit tests for API, integration tests, and React Testing Library tests"
829
-
830
- # 3. Run the entire pipeline
831
- node wbs.js job run wbs-5
832
- ```
833
-
834
- **Agent selection rationale:**
835
- - `@claude:sonnet`: Complex logic, architecture, React components
836
- - `@claude:opus`: Very complex architectural decisions
837
- - `@copilot`: Straightforward implementation, test generation
838
- - `@gemini`: Performance optimization, data analysis (not shown here)
839
-
840
- ---
841
-
842
- ### Example 6: Working with Detail Documents
843
-
844
- Use detail documents to provide comprehensive context to all jobs.
845
-
846
- ```bash
847
- # 1. Create project with detail document
848
- node wbs.js create "E-commerce Checkout Flow" --detail ./docs/checkout-spec.md
849
-
850
- # The system creates: skills/wbs/details/wbs-6-detail.md
851
- ```
852
-
853
- **Edit the detail document:**
854
-
855
- ```bash
856
- # Edit skills/wbs/details/wbs-6-detail.md
857
- ```
858
-
859
- **Content:**
860
- ```markdown
861
- # E-commerce Checkout Flow
862
-
863
- ## Overview
864
- Implement a secure checkout process for our e-commerce platform.
865
-
866
- ## Requirements
867
-
868
- ### Functional Requirements
869
- 1. Multi-step checkout (cart → shipping → payment → confirmation)
870
- 2. Address validation with autocomplete
871
- 3. Multiple payment methods (credit card, PayPal)
872
- 4. Order summary with promo codes
873
- 5. Email confirmation
874
-
875
- ### Technical Requirements
876
- - Payment processing via Stripe
877
- - Address validation via Google Maps API
878
- - Session management for cart persistence
879
- - Transactional email via SendGrid
880
-
881
- ### Security
882
- - PCI compliance for credit card handling
883
- - HTTPS only
884
- - CSRF protection
885
- - Rate limiting on payment endpoints
886
-
887
- ### Performance
888
- - Checkout flow should complete in < 3 seconds
889
- - Optimize for mobile devices
890
-
891
- ## References
892
- - [Stripe API Docs](https://stripe.com/docs/api)
893
- - [Design Mockups](./figma-link)
894
- ```
895
-
896
- **Add jobs:**
897
- ```bash
898
- node wbs.js job add wbs-6 \
899
- --title "Implement multi-step form navigation" \
900
- --agent "@claude:sonnet" \
901
- --seq 1
902
-
903
- node wbs.js job add wbs-6 \
904
- --title "Integrate Stripe payment" \
905
- --agent "@copilot" \
906
- --seq 2
907
-
908
- # ... more jobs
909
- ```
910
-
911
- **When jobs run, they automatically receive the detail document content as context.**
912
-
913
- ---
914
-
915
- ### Example 7: Monitoring and JSON Output
916
-
917
- Automate WBS monitoring and integrate with other tools.
918
-
919
- **Check project status programmatically:**
920
- ```bash
921
- # Get JSON output for scripting
922
- node wbs.js status wbs-1 --json | jq '.summary'
923
- ```
924
-
925
- **Output:**
926
- ```json
927
- {
928
- "total_jobs": 4,
929
- "completed": 4,
930
- "failed": 0,
931
- "pending": 0,
932
- "running": 0,
933
- "progress": 100
934
- }
935
- ```
936
-
937
- **Create a monitoring script:**
938
- ```bash
939
- #!/bin/bash
940
- # monitor-wbs.sh
941
-
942
- WBS_ID="wbs-7"
943
-
944
- while true; do
945
- clear
946
- echo "═══════════════════════════════════════"
947
- echo " WBS Monitor - $WBS_ID"
948
- echo "═══════════════════════════════════════"
949
-
950
- node wbs.js status $WBS_ID
951
-
952
- PROGRESS=$(node wbs.js status $WBS_ID --json | jq -r '.summary.progress')
953
-
954
- if [ "$PROGRESS" -eq 100 ]; then
955
- echo ""
956
- echo "✅ Project complete!"
957
- break
958
- fi
959
-
960
- echo ""
961
- echo "⏳ Checking again in 60 seconds..."
962
- sleep 60
963
- done
964
- ```
965
-
966
- **Run monitor:**
967
- ```bash
968
- chmod +x monitor-wbs.sh
969
- ./monitor-wbs.sh
970
- ```
971
-
972
- **Export jobs to CSV:**
973
- ```bash
974
- # Export job list
975
- echo "ID,Title,Status,Agent,Seq" > jobs-export.csv
976
- node wbs.js job list wbs-1 --json | \
977
- jq -r '.[] | [.id,.title,.status,.agent,.seq] | @csv' >> jobs-export.csv
978
- ```
979
-
980
- **Check specific job execution history:**
981
- ```bash
982
- # List all executions for a job
983
- node wbs.js exec list job-5 --json | jq '.'
984
- ```
985
-
986
- ---
987
-
988
- ### Example 8: Recovering from Interruptions
989
-
990
- Handle scenarios where execution is interrupted.
991
-
992
- **Scenario**: Long-running project interrupted by system crash
993
-
994
- ```bash
995
- # 1. Check current status
996
- node wbs.js list
997
- ```
998
-
999
- **Output:**
1000
- ```
1001
- 📋 WBS Projects (3)
1002
-
1003
- | ID | 제목 | 상태 | 진행 |
1004
- |-------|-----------------------|----------|----------|
1005
- | wbs-1 | Todo REST API | completed| 100% 4/4 |
1006
- | wbs-2 | Bug Fixes | running | 50% 2/4 |
1007
- | wbs-3 | Refactoring | planning | 0% 0/5 |
1008
- ```
1009
-
1010
- ```bash
1011
- # 2. Check which jobs were running
1012
- node wbs.js status wbs-2
1013
- ```
1014
-
1015
- **Output:**
1016
- ```
1017
- 📋 Bug Fixes (wbs-2)
1018
- Status: running | Progress: 50% (2/4)
1019
-
1020
- Jobs:
1021
- | 상태 | # | ID | 작업명 | Status |
1022
- |------|----|----|---------------|-----------|
1023
- | ✅ | 1 | job-1 | Fix bug #123 | completed |
1024
- | ✅ | 2 | job-2 | Fix bug #124 | completed |
1025
- | 🟡 | 3 | job-3 | Fix bug #125 | running |
1026
- | ⬜️ | 4 | job-4 | Fix bug #126 | pending |
1027
- ```
1028
-
1029
- ```bash
1030
- # 3. Check if the running job actually completed
1031
- node wbs.js exec list job-3
1032
- ```
1033
-
1034
- **If the execution failed or timed out:**
1035
- ```
1036
- | 상태 | ID | PID | 시작 | 종료 | 코드 |
1037
- |------|---------|-------|---------------------|---------------------|------|
1038
- | ❌ | exec-7 | 23456 | 2025-12-18 10:30:00 | N/A (timeout) | -1 |
1039
- ```
1040
-
1041
- ```bash
1042
- # 4. Reset the job and retry
1043
- node wbs.js job update job-3 --status pending
1044
- node wbs.js job retry job-3
1045
-
1046
- # 5. Continue with remaining jobs
1047
- node wbs.js job run wbs-2
1048
- ```
1049
-
1050
- ---
1051
-
1052
- ### Summary: Quick Command Reference
1053
-
1054
- **Basic workflow:**
1055
- ```bash
1056
- # Create → Add → Run → Check
1057
- node wbs.js create "Project Name"
1058
- node wbs.js job add wbs-X --title "Task" --agent "@agent" --seq N
1059
- node wbs.js job run wbs-X
1060
- node wbs.js status wbs-X
1061
- ```
1062
-
1063
- **Issue-based workflow:**
1064
- ```bash
1065
- node wbs.js create "Bug Fixes"
1066
- node wbs.js job add wbs-X --title "Fix bug" --agent "@agent" --issue 123
1067
- node wbs.js job run wbs-X
1068
- ```
1069
-
1070
- **Step-by-step workflow:**
1071
- ```bash
1072
- node wbs.js job next wbs-X # Run one job
1073
- # Review changes...
1074
- node wbs.js job next wbs-X # Run next
1075
- ```
1076
-
1077
- **Handle failures (job-id or slug):**
1078
- ```bash
1079
- node wbs.js job list wbs-X --json | jq '.[] | select(.status=="failed")'
1080
- node wbs.js job update wbs-X-Y --desc "Updated instructions" # by slug
1081
- node wbs.js job retry wbs-X-Y # by slug
1082
- node wbs.js job retry job-Y # by job-id
1083
- ```
1084
-
1085
- **Monitoring:**
1086
- ```bash
1087
- node wbs.js list
1088
- node wbs.js status wbs-X
1089
- node wbs.js status wbs-X --json | jq '.summary'
1090
- ```
1091
-
1092
- For more examples, see:
1093
- - [EXAMPLE.md](./EXAMPLE.md) - Korean language detailed walkthrough
1094
- - [job-management.md](./job-management.md) - Job-specific examples and patterns
1095
-
1096
- ## Usage in Coordinator Agent
1097
-
1098
- The coordinator agent uses this skill programmatically:
1099
-
1100
- ```javascript
1101
- const wbs = require('./wbs.js');
1102
-
1103
- // 1. Create project
1104
- const id = wbs.create('User Authentication Implementation');
1105
-
1106
- // 2. Add jobs (AI decomposed)
1107
- wbs.addJob(id, { title: 'Design User model', agent: '@claude:sonnet', seq: 1 });
1108
- wbs.addJob(id, { title: 'Implement login API', agent: '@copilot', seq: 2 });
1109
- wbs.addJob(id, { title: 'Write tests', agent: '@claude:sonnet', seq: 3 });
1110
-
1111
- // 3. Execute
1112
- await wbs.run(id);
1113
-
1114
- // 4. Check status
1115
- console.log(wbs.status(id));
1116
- ```
1117
-
1118
- ## Job Status Flow
1119
-
1120
- ```
1121
- pending → running → completed
1122
- → failed
1123
- ```
1124
-
1125
- ## Key Design Decisions
1126
-
1127
- 1. **AI makes intelligent decisions** - Complexity analysis, job decomposition
1128
- 2. **Code handles state only** - wbs.js does DB CRUD + worker execution
1129
- 3. **30-minute timeboxing** - Each job is 15-45 minutes
1130
- 4. **Start simple, improve iteratively** - MVP first
1131
-
1132
- ## API Reference
1133
-
1134
- ### Project Management
1135
-
1136
- #### `wbs.create(title, options?)`
1137
- Create a new WBS project. Returns project ID.
1138
- - `options.detailPath`: Path to detail document (auto-created if not specified)
1139
-
1140
- #### `wbs.list()`
1141
- List all WBS projects.
1142
-
1143
- #### `wbs.status(wbsId)`
1144
- Get project and all jobs status.
1145
-
1146
- #### `wbs.delete(wbsId)`
1147
- Delete a project and all associated jobs/executions.
1148
-
1149
- ### Job Management
1150
-
1151
- #### `wbs.addJob(wbsId, { title, description?, agent, seq?, issue_number? })`
1152
- Add a job to the project. Returns job ID.
1153
- - `title`: Job title (short name)
1154
- - `description`: Detailed instructions for the agent
1155
- - `agent`: Worker agent mention (e.g., `@crewx_claude_dev`)
1156
- - `seq`: Execution order (default: 0)
1157
- - `issue_number`: Related GitHub issue number
1158
-
1159
- #### `wbs.getNextJob(wbsId)`
1160
- Get the next pending job. Returns job object or null.
1161
-
1162
- #### `wbs.updateJob(jobId, status)`
1163
- Update job status. Status: `pending`, `running`, `completed`, `failed`.
1164
-
1165
- #### `wbs.runWorker(job)`
1166
- Execute a single worker. Returns `{ success, error?, execId }`.
1167
-
1168
- #### `wbs.run(wbsId)`
1169
- Execute all pending jobs sequentially.
1170
-
1171
- ### Execution Management
1172
-
1173
- #### `wbs.createExecution(jobId, pid)`
1174
- Create a new execution record. Returns execution ID.
1175
-
1176
- #### `wbs.updateExecution(execId, status, options?)`
1177
- Update execution status.
1178
- - `options.exitCode`: Process exit code
1179
- - `options.error`: Error message
1180
-
1181
- #### `wbs.getExecution(execId)`
1182
- Get execution by ID.
1183
-
1184
- #### `wbs.listExecutions(jobId)`
1185
- List all executions for a job.
1186
-
1187
- #### `wbs.killExecution(execId)`
1188
- Kill a running execution. Returns boolean success.
1189
-
1190
- #### `wbs.getRunningExecutions()`
1191
- Get all currently running executions.
1192
-
1193
- ## Related Documentation
1194
-
1195
- - [WBS Skill Spec](/docs/cto/designs/wbs-skill-spec.md)
1196
- - [CrewX CLI Documentation](/packages/cli/AGENTS.md)
1
+ ---
2
+ name: crewx/wbs
3
+ description: Work Breakdown Structure (WBS) management skill. Enables AI coordinators to decompose complex tasks into 30-minute timeboxed jobs and execute them via worker agents.
4
+ metadata:
5
+ version: 0.3.0
6
+ built-in: true
7
+ ---
8
+
9
+ # WBS Skill
10
+
11
+ Provides state management and worker execution for Work Breakdown Structure based task decomposition.
12
+
13
+ ## Core Principle
14
+
15
+ **System provides state management, AI agent makes intelligent decisions.**
16
+
17
+ ```
18
+ User Request
19
+ |
20
+ v
21
+ +-----------------------------------------------------+
22
+ | Coordinator Agent (with WBS skill) |
23
+ | - Analyze request (AI judgment) |
24
+ | - Decompose into 30-min Jobs (AI judgment) |
25
+ | - Execute workers: crewx x "@agent action" |
26
+ | - Track state: wbs.js |
27
+ +-----------------------------------------------------+
28
+ |
29
+ +---------------+--------------+
30
+ v v v
31
+ +---------+ +---------+ +---------+
32
+ | Worker1 | | Worker2 | | Worker3 |
33
+ | @claude | | @gemini | | @copilot|
34
+ +---------+ +---------+ +---------+
35
+ ```
36
+
37
+ ## What is WBS Skill?
38
+
39
+ The WBS (Work Breakdown Structure) skill is a **project management system for complex AI-driven tasks**. It enables coordinator agents to:
40
+
41
+ 1. **Decompose complex tasks** into manageable 30-minute jobs
42
+ 2. **Track progress** with state management (pending -> running -> completed/failed)
43
+ 3. **Coordinate multiple agents** by assigning different jobs to specialized workers
44
+ 4. **Manage context** through detail documents and structured workflow
45
+ 5. **Execute in parallel** by distributing jobs across multiple worker agents
46
+
47
+ ### Key Characteristics
48
+
49
+ - **Structured Approach**: Projects are broken down into jobs with clear status tracking
50
+ - **Time-Boxed Execution**: Each job targets 15-45 minutes (optimal: 25-30 min)
51
+ - **Multi-Agent Coordination**: Different jobs can be assigned to different AI agents
52
+ - **State Persistence**: All project data, jobs, and execution history are tracked in `.wbs-data.json`
53
+ - **Automated Workflow**: Git branching, PR templates, and issue tracking integration
54
+ - **Job Slug System**: Jobs are identified by intuitive slugs (`wbs-5-1`, `wbs-5-2`) computed from `wbs_id + seq`
55
+ - **Auto-generated Detail Files**: `job add` automatically generates/updates `wbs-details/wbs-{N}-detail.md` with job metadata
56
+
57
+ ## Job Slug System
58
+
59
+ Each job gets a **slug** computed from its WBS ID and sequence number: `wbs-{N}-{seq}`
60
+
61
+ | Internal ID | Slug | Meaning |
62
+ |------------|------|---------|
63
+ | `job-15` | `wbs-5-1` | 1st Job of WBS-5 |
64
+ | `job-16` | `wbs-5-2` | 2nd Job of WBS-5 |
65
+ | `job-17` | `wbs-5-3` | 3rd Job of WBS-5 |
66
+
67
+ - Slugs are **computed values** (not stored in DB) -- derived from `wbs_id` + `seq`
68
+ - All commands accepting `<job-id>` also accept `<slug>`: `wbs job update wbs-5-1 --status completed`
69
+ - Git branches use slug naming: `feature/wbs-5-1`
70
+ - Worktree directories align with slug naming
71
+
72
+ ## When to Use WBS Skill
73
+
74
+ ### Use WBS When
75
+
76
+ Choose WBS for tasks that meet **any** of these criteria:
77
+
78
+ - **Complex multi-step tasks** (> 45 minutes total)
79
+ - Feature implementations spanning multiple files/modules
80
+ - Large-scale refactoring projects
81
+ - Bug fix sprints with multiple related issues
82
+
83
+ - **30-minute timeboxing needed**
84
+ - Tasks prone to context loss (LLM "Lost in the Middle" problem)
85
+ - Work requiring periodic checkpoints and validation
86
+ - Projects where partial progress needs to be tracked
87
+
88
+ - **Parallel execution beneficial**
89
+ - Jobs that can be distributed across multiple worker agents
90
+ - Tasks where different agents excel at different subtasks
91
+ - Work that benefits from concurrent execution
92
+
93
+ - **Progress tracking important**
94
+ - Team collaboration requiring visibility into task status
95
+ - Projects with external stakeholders needing updates
96
+ - Work where partial failure recovery is critical
97
+
98
+ - **GitHub integration needed**
99
+ - Tasks linked to GitHub issues
100
+ - Projects requiring structured PR workflows
101
+ - Work following standardized git branching strategies
102
+
103
+ ### Use Direct Delegation When
104
+
105
+ Skip WBS for simpler scenarios:
106
+
107
+ - Single-step tasks (< 15 minutes)
108
+ - One-off file modifications
109
+ - Quick code analysis or queries
110
+ - Rapid prototyping without tracking needs
111
+ - Tasks with no need for state persistence
112
+
113
+ ### Decision Flow
114
+
115
+ ```
116
+ Task received
117
+ |
118
+ v
119
+ Expected duration?
120
+ |
121
+ +--- < 15 min ----------------------> Direct Delegation
122
+ |
123
+ +--- 15-45 min -+- Single step ------> Direct Delegation
124
+ | +- Multi-step --------> WBS Skill
125
+ |
126
+ +--- > 45 min ----------------------> WBS Skill (required)
127
+ ```
128
+
129
+ ## Use Case Examples
130
+
131
+ ### 1. Complex Feature Implementation
132
+
133
+ **Scenario**: Implement user authentication system
134
+
135
+ ```bash
136
+ # WBS approach - structured and tracked
137
+ wbs.js create "User Authentication Implementation"
138
+ wbs.js job add wbs-1 --title "Design User model" --agent "@claude:sonnet" --seq 1
139
+ wbs.js job add wbs-1 --title "Implement login API" --agent "@copilot" --seq 2
140
+ wbs.js job add wbs-1 --title "Add JWT handling" --agent "@copilot" --seq 3
141
+ wbs.js job add wbs-1 --title "Write unit tests" --agent "@claude:sonnet" --seq 4
142
+ wbs.js job run wbs-1
143
+ ```
144
+
145
+ **Why WBS**: Multi-step process, multiple agents, progress tracking needed
146
+
147
+ ### 2. Bug Fix Sprint
148
+
149
+ **Scenario**: Fix multiple related authentication bugs
150
+
151
+ ```bash
152
+ # WBS approach - organized issue resolution
153
+ wbs.js create "Bug Fix Sprint"
154
+ wbs.js job add wbs-2 --title "Fix login bug" --agent "@claude" --issue 42 --seq 1
155
+ wbs.js job add wbs-2 --title "Fix session timeout" --agent "@claude" --issue 43 --seq 2
156
+ wbs.js job add wbs-2 --title "Fix password reset" --agent "@claude" --issue 44 --seq 3
157
+ wbs.js job run wbs-2
158
+ ```
159
+
160
+ **Why WBS**: Multiple issues, GitHub integration, failure recovery important
161
+
162
+ ### 3. Large Refactoring
163
+
164
+ **Scenario**: Refactor API layer across multiple modules
165
+
166
+ ```bash
167
+ # WBS approach - context preservation across modules
168
+ wbs.js create "API Refactoring"
169
+ wbs.js job add wbs-3 --title "Refactor auth module" --agent "@claude" --seq 1
170
+ wbs.js job add wbs-3 --title "Refactor user module" --agent "@claude" --seq 2
171
+ wbs.js job add wbs-3 --title "Update tests" --agent "@copilot" --seq 3
172
+ wbs.js job run wbs-3
173
+ ```
174
+
175
+ **Why WBS**: Context preservation critical, step-by-step validation needed
176
+
177
+ ### 4. Simple Code Fix (No WBS)
178
+
179
+ **Scenario**: Fix a typo in documentation
180
+
181
+ ```bash
182
+ # Direct delegation - immediate execution
183
+ crewx x "@claude Fix typo in README.md line 42"
184
+ ```
185
+
186
+ **Why Direct**: Single-step, < 15 minutes, no tracking needed
187
+
188
+ ## 30-Minute Timeboxing
189
+
190
+ | Category | Time | Description |
191
+ |----------|------|-------------|
192
+ | Minimum | 15 min | Below this -> don't separate as Job |
193
+ | Optimal | 25-30 min | Target duration |
194
+ | Maximum | 45 min | Above this -> re-decompose |
195
+
196
+ **Rationale**: LLM context limits (Lost in the Middle, Context Rot) + Pomodoro Technique
197
+
198
+ ## WARNING: Job Description Template (MANDATORY)
199
+
200
+ **All Jobs must follow the template below.** Vague Job Descriptions are a leading cause of incomplete work.
201
+
202
+ ### Template
203
+
204
+ ```markdown
205
+ **Deliverables:**
206
+ 1. path/to/file1.tsx - description
207
+ 2. path/to/file2.ts - description
208
+ 3. Modify existing file: path/to/existing.tsx
209
+
210
+ **Done Criteria:**
211
+ - [ ] Verify component rendering
212
+ - [ ] Verify store integration works
213
+ - [ ] Verify route addition and navigation
214
+
215
+ **References:**
216
+ - docs/ui-screens/screens/XX.md
217
+ - Wireframe/design links
218
+ ```
219
+
220
+ ### Usage Example
221
+
222
+ ```bash
223
+ # [BAD] BAD - Vague Job Description
224
+ node wbs.js job add wbs-1 \
225
+ --title "Agent settings screen" \
226
+ --desc "Display crewx.yaml agent list. Model/provider/prompt editing UI." \
227
+ --agent "@launcher_gemini_dev"
228
+
229
+ # [OK] GOOD - Clear deliverables and done criteria
230
+ node wbs.js job add wbs-1 \
231
+ --title "Agent settings screen" \
232
+ --desc "**Deliverables:**
233
+ 1. src/renderer/components/AgentConfig/AgentConfigPage.tsx - Agent list page
234
+ 2. src/renderer/components/AgentConfig/AgentEditModal.tsx - Edit modal
235
+ 3. src/renderer/App.tsx - Add /agents route
236
+ 4. src/renderer/components/Layout/Sidebar.tsx - Add menu item
237
+
238
+ **Done Criteria:**
239
+ - [ ] Agent list displays when navigating to /agents
240
+ - [ ] Edit modal opens on button click
241
+ - [ ] Changes saved to crewx.yaml on save
242
+
243
+ **References:** docs/ui-screens/screens/03-agent.md" \
244
+ --agent "@launcher_gemini_dev"
245
+ ```
246
+
247
+ ### Why Is This Mandatory?
248
+
249
+ | Problem | Vague Job Description | With Template |
250
+ |---------|----------------------|---------------|
251
+ | **Scope interpretation** | Agent interprets arbitrarily | Clear file list |
252
+ | **Completion judgment** | Manual "done" marking | Checklist verification |
253
+ | **Preventing omissions** | Only Store without UI | All deliverables specified |
254
+ | **Review ease** | Unclear what to verify | Checklist-based review |
255
+
256
+ ### Integration Test Job Template
257
+
258
+ Integration test Jobs must specify verification items in detail:
259
+
260
+ ```bash
261
+ node wbs.js job add wbs-1 \
262
+ --title "Integration test" \
263
+ --desc "**Verification Scenarios:**
264
+ 1. Onboarding -> Preset selection -> Installation complete
265
+ 2. Dashboard -> Agent list displays
266
+ 3. Agent settings -> Edit -> Save
267
+
268
+ **Verification Methods:**
269
+ - [ ] Manual execution of each scenario
270
+ - [ ] Screenshot capture (using skills/playwright-python)
271
+ - [ ] Error log inspection
272
+
273
+ **Pass Criteria:**
274
+ - All scenarios work correctly
275
+ - No console errors" \
276
+ --agent "@launcher_codex_dev"
277
+ ```
278
+
279
+ ## Installation
280
+
281
+ ```bash
282
+ cd skills/wbs
283
+ npm install
284
+ ```
285
+
286
+ Requires Node.js 16+.
287
+
288
+ ## Commands Reference
289
+
290
+ ### Project Management Commands
291
+
292
+ | Command | Syntax | Description |
293
+ |---------|--------|-------------|
294
+ | **create** | `wbs.js create "Title" [--detail path]` | Create new WBS project with sequential ID (wbs-1, wbs-2, ...) |
295
+ | **list** | `wbs.js list [--json]` | List all projects with status and progress |
296
+ | **status** | `wbs.js status <wbs-id> [--json]` | Get detailed project info including all jobs and summary stats |
297
+ | **delete** | `wbs.js delete <wbs-id>` | Delete project and all associated jobs/executions (irreversible) |
298
+
299
+ ### Job Management Commands
300
+
301
+ | Command | Syntax | Description |
302
+ |---------|--------|-------------|
303
+ | **job add** | `wbs.js job add <wbs-id> --title "Title" --agent "@agent" [options]` | Add new job to project. Options: `--desc`, `--seq`, `--issue` |
304
+ | **job list** | `wbs.js job list <wbs-id> [--json]` | List all jobs ordered by sequence number |
305
+ | **job update** | `wbs.js job update <job-id\|slug> [options]` | Update job properties. Options: `--status`, `--title`, `--desc`, `--agent`, `--seq`, `--issue` |
306
+ | **job run** | `wbs.js job run <wbs-id>` | Execute all pending jobs sequentially (30-min timeout each) |
307
+ | **job next** | `wbs.js job next <wbs-id>` | Execute only the next pending job (manual step-by-step) |
308
+ | **job retry** | `wbs.js job retry <job-id\|slug>` | Retry a failed or completed job |
309
+
310
+ ### Execution Management Commands
311
+
312
+ | Command | Syntax | Description |
313
+ |---------|--------|-------------|
314
+ | **exec list** | `wbs.js exec list <job-id\|slug> [--json]` | List execution history for a job |
315
+ | **exec status** | `wbs.js exec status <exec-id> [--json]` | Get detailed execution info |
316
+ | **exec kill** | `wbs.js exec kill <exec-id>` | Kill a running execution |
317
+ | **exec running** | `wbs.js exec running [--json]` | List all currently running executions |
318
+
319
+ ### Coordinator Commands (Natural Language)
320
+
321
+ | Command | Syntax | Description |
322
+ |---------|--------|-------------|
323
+ | **q** | `wbs.js q "question"` | Ask coordinator a question (via `@wbs_coordinator`) |
324
+ | **x** | `wbs.js x "request"` | Request coordinator to execute an action |
325
+
326
+ ### Daemon Commands (Background Scheduler)
327
+
328
+ | Command | Syntax | Description |
329
+ |---------|--------|-------------|
330
+ | **daemon start** | `wbs.js daemon start` | Start background scheduler |
331
+ | **daemon stop** | `wbs.js daemon stop` | Stop running daemon |
332
+ | **daemon status** | `wbs.js daemon status` | Check daemon status |
333
+ | **daemon tick** | `wbs.js daemon tick` | Manual tick for testing |
334
+
335
+ ### Common Usage Patterns
336
+
337
+ ```bash
338
+ # Create and run a complete project
339
+ wbs.js create "User Authentication"
340
+ wbs.js job add wbs-1 --title "Design schema" --agent "@claude:sonnet" --seq 1
341
+ wbs.js job add wbs-1 --title "Implement API" --agent "@copilot" --seq 2
342
+ wbs.js job add wbs-1 --title "Write tests" --agent "@claude:sonnet" --seq 3
343
+ wbs.js job run wbs-1
344
+
345
+ # Check progress
346
+ wbs.js status wbs-1
347
+
348
+ # Handle failures (use job-id or slug)
349
+ wbs.js job list wbs-1 --json | jq '.[] | select(.status=="failed")'
350
+ wbs.js job retry wbs-1-3 # by slug
351
+ wbs.js job retry job-5 # by job-id
352
+
353
+ # Issue-based workflow
354
+ wbs.js job add wbs-2 --title "Fix bug" --agent "@claude" --issue 42
355
+ ```
356
+
357
+ ### Output Formats
358
+
359
+ - **Default**: Human-readable tables with emoji status icons
360
+ - **--json**: Machine-parseable JSON for scripting and automation
361
+
362
+ For detailed command documentation, see:
363
+ - [COMMANDS.md](./COMMANDS.md) - Complete project commands reference
364
+ - [job-management.md](./job-management.md) - Comprehensive job management guide
365
+
366
+ ## Practical Usage Examples
367
+
368
+ This section provides comprehensive real-world examples of using the WBS skill effectively.
369
+
370
+ ### Example 1: Simple Workflow (Create -> Add Jobs -> Run)
371
+
372
+ The most basic WBS workflow involves creating a project, adding jobs, and running them sequentially.
373
+
374
+ **Scenario**: Build a simple REST API for a todo application
375
+
376
+ ```bash
377
+ # 1. Create the project
378
+ node wbs.js create "Todo REST API"
379
+ ```
380
+
381
+ **Expected output:**
382
+ ```json
383
+ {
384
+ "id": "wbs-1",
385
+ "title": "Todo REST API",
386
+ "status": "planning",
387
+ "detailPath": "skills/wbs/details/wbs-1-detail.md",
388
+ "created_at": "2025-12-18T08:00:00.000Z"
389
+ }
390
+ ```
391
+
392
+ ```bash
393
+ # 2. Add jobs for implementation
394
+ node wbs.js job add wbs-1 \
395
+ --title "Design database schema" \
396
+ --agent "@claude:sonnet" \
397
+ --seq 1 \
398
+ --desc "Create SQLite schema for todos table with id, title, completed, created_at fields"
399
+
400
+ node wbs.js job add wbs-1 \
401
+ --title "Implement CRUD endpoints" \
402
+ --agent "@copilot" \
403
+ --seq 2 \
404
+ --desc "Create Express routes: GET /todos, POST /todos, PUT /todos/:id, DELETE /todos/:id"
405
+
406
+ node wbs.js job add wbs-1 \
407
+ --title "Add input validation" \
408
+ --agent "@claude:sonnet" \
409
+ --seq 3 \
410
+ --desc "Implement request validation middleware using express-validator"
411
+
412
+ node wbs.js job add wbs-1 \
413
+ --title "Write integration tests" \
414
+ --agent "@copilot" \
415
+ --seq 4 \
416
+ --desc "Create test suite covering all CRUD operations using supertest"
417
+ ```
418
+
419
+ ```bash
420
+ # 3. Review the planned jobs
421
+ node wbs.js status wbs-1
422
+ ```
423
+
424
+ **Expected output:**
425
+ ```
426
+ [INFO] Todo REST API (wbs-1)
427
+ Status: planning | Progress: 0% (0/4)
428
+ Detail: skills/wbs/details/wbs-1-detail.md
429
+
430
+ Jobs:
431
+ | Status | # | Slug | ID | Task | Agent |
432
+ |--------|----|-----------|-------|--------------------------|-----------------|
433
+ | [ ] | 1 | wbs-1-1 | job-1 | Design database schema | @claude:sonnet |
434
+ | [ ] | 2 | wbs-1-2 | job-2 | Implement CRUD endpoints | @copilot |
435
+ | [ ] | 3 | wbs-1-3 | job-3 | Add input validation | @claude:sonnet |
436
+ | [ ] | 4 | wbs-1-4 | job-4 | Write integration tests | @copilot |
437
+ ```
438
+
439
+ ```bash
440
+ # 4. Run all jobs
441
+ node wbs.js job run wbs-1
442
+ ```
443
+
444
+ **Expected output:**
445
+ ```
446
+ ==================================================
447
+ [WBS] Starting project: Todo REST API
448
+ ==================================================
449
+
450
+ [WBS] Running job: Design database schema
451
+ [WBS] Agent: @claude:sonnet
452
+ [WBS] Description: Create SQLite schema for todos table...
453
+ [WBS] Timeout: 30 minutes
454
+ --------------------------------------------------
455
+ [Agent executes and produces output...]
456
+ --------------------------------------------------
457
+ [WBS] Job completed: Design database schema
458
+
459
+ [WBS] Running job: Implement CRUD endpoints
460
+ [WBS] Agent: @copilot
461
+ [WBS] Timeout: 30 minutes
462
+ --------------------------------------------------
463
+ [Agent executes and produces output...]
464
+ --------------------------------------------------
465
+ [WBS] Job completed: Implement CRUD endpoints
466
+
467
+ [... continues for remaining jobs ...]
468
+
469
+ ==================================================
470
+ [WBS] Project completed: Todo REST API
471
+ [WBS] Completed: 4, Failed: 0
472
+ ==================================================
473
+ ```
474
+
475
+ ```bash
476
+ # 5. Verify completion
477
+ node wbs.js status wbs-1
478
+ ```
479
+
480
+ **Final output:**
481
+ ```
482
+ [INFO] Todo REST API (wbs-1)
483
+ Status: completed | Progress: 100% (4/4)
484
+ Detail: skills/wbs/details/wbs-1-detail.md
485
+
486
+ Jobs:
487
+ | Status | # | Slug | ID | Task | Agent | Status |
488
+ |--------|----|-----------|-------|--------------------------|-----------------|-----------|
489
+ | [OK] | 1 | wbs-1-1 | job-1 | Design database schema | @claude:sonnet | completed |
490
+ | [OK] | 2 | wbs-1-2 | job-2 | Implement CRUD endpoints | @copilot | completed |
491
+ | [OK] | 3 | wbs-1-3 | job-3 | Add input validation | @claude:sonnet | completed |
492
+ | [OK] | 4 | wbs-1-4 | job-4 | Write integration tests | @copilot | completed |
493
+ ```
494
+
495
+ ---
496
+
497
+ ### Example 2: Issue-Based Workflow
498
+
499
+ Use WBS to manage multiple GitHub issues systematically.
500
+
501
+ **Scenario**: Fix authentication-related bugs tracked in GitHub
502
+
503
+ ```bash
504
+ # 1. Create project for bug fixes
505
+ node wbs.js create "Authentication Bug Fixes"
506
+ ```
507
+
508
+ **Output:**
509
+ ```json
510
+ {
511
+ "id": "wbs-2",
512
+ "title": "Authentication Bug Fixes",
513
+ "status": "planning"
514
+ }
515
+ ```
516
+
517
+ ```bash
518
+ # 2. Add jobs linked to GitHub issues
519
+ node wbs.js job add wbs-2 \
520
+ --title "Fix: Login fails with special characters in password" \
521
+ --agent "@claude:sonnet" \
522
+ --issue 123 \
523
+ --seq 1
524
+
525
+ node wbs.js job add wbs-2 \
526
+ --title "Fix: Session timeout not working" \
527
+ --agent "@claude:sonnet" \
528
+ --issue 124 \
529
+ --seq 2
530
+
531
+ node wbs.js job add wbs-2 \
532
+ --title "Fix: Password reset email not sent" \
533
+ --agent "@claude:sonnet" \
534
+ --issue 125 \
535
+ --seq 3
536
+ ```
537
+
538
+ **What happens during execution:**
539
+
540
+ When you run `node wbs.js job run wbs-2`, each job receives these instructions:
541
+
542
+ ```
543
+ ## Task Instructions
544
+ Process GitHub Issue #123.
545
+
546
+ **Follow your existing development process:**
547
+ 1. Check the issue with `gh issue view 123`
548
+ 2. Create branch and work
549
+ 3. Create PR
550
+ 4. Comment results on the issue
551
+
552
+ WBS Tracking Info:
553
+ - WBS: wbs-2
554
+ - Job: job-1
555
+ ```
556
+
557
+ **Advantages:**
558
+ - Automatic issue-branch-PR linking
559
+ - Agent follows its own development workflow
560
+ - Easy progress tracking via GitHub
561
+ - Issue comments document resolution
562
+
563
+ ---
564
+
565
+ ### Example 3: Step-by-Step Execution
566
+
567
+ Execute jobs manually one at a time with review between each step.
568
+
569
+ **Scenario**: Refactoring legacy code where each step needs verification
570
+
571
+ ```bash
572
+ # 1. Create project
573
+ node wbs.js create "Legacy Code Refactoring"
574
+
575
+ # 2. Add jobs
576
+ node wbs.js job add wbs-3 \
577
+ --title "Extract UserService from monolithic controller" \
578
+ --agent "@claude:opus" \
579
+ --seq 1 \
580
+ --desc "Move user-related logic from AppController to new UserService class"
581
+
582
+ node wbs.js job add wbs-3 \
583
+ --title "Add dependency injection" \
584
+ --agent "@claude:sonnet" \
585
+ --seq 2 \
586
+ --desc "Refactor UserService to use constructor injection for database"
587
+
588
+ node wbs.js job add wbs-3 \
589
+ --title "Update unit tests" \
590
+ --agent "@copilot" \
591
+ --seq 3 \
592
+ --desc "Modify tests to work with new UserService architecture"
593
+
594
+ node wbs.js job add wbs-3 \
595
+ --title "Verify integration tests pass" \
596
+ --agent "@copilot" \
597
+ --seq 4 \
598
+ --desc "Run full test suite and fix any integration issues"
599
+ ```
600
+
601
+ ```bash
602
+ # 3. Execute first job only
603
+ node wbs.js job next wbs-3
604
+ ```
605
+
606
+ **Output:**
607
+ ```
608
+ [WBS] Running job: Extract UserService from monolithic controller
609
+ [WBS] Agent: @claude:opus
610
+ [WBS] Timeout: 30 minutes
611
+ --------------------------------------------------
612
+ [Agent output...]
613
+ --------------------------------------------------
614
+ [WBS] Job completed: Extract UserService from monolithic controller
615
+
616
+ {
617
+ "success": true,
618
+ "execId": "exec-1"
619
+ }
620
+ ```
621
+
622
+ ```bash
623
+ # 4. Review changes before continuing
624
+ git diff
625
+ npm test
626
+
627
+ # 5. If satisfied, run next job
628
+ node wbs.js job next wbs-3
629
+ ```
630
+
631
+ **Output:**
632
+ ```
633
+ [WBS] Running job: Add dependency injection
634
+ [WBS] Agent: @claude:sonnet
635
+ ...
636
+ ```
637
+
638
+ ```bash
639
+ # 6. Continue step by step
640
+ node wbs.js status wbs-3 # Check progress
641
+ node wbs.js job next wbs-3 # Run next job
642
+ ```
643
+
644
+ **Use cases for step-by-step execution:**
645
+ - Code reviews between steps
646
+ - Testing after each change
647
+ - Learning/understanding the codebase
648
+ - High-risk refactoring
649
+ - Debugging job configurations
650
+
651
+ ---
652
+
653
+ ### Example 4: Handling Failures
654
+
655
+ Recover from failed jobs and retry with updated configurations.
656
+
657
+ **Scenario**: API implementation where initial attempts fail
658
+
659
+ ```bash
660
+ # 1. Create project and add jobs
661
+ node wbs.js create "Payment API Integration"
662
+
663
+ node wbs.js job add wbs-4 \
664
+ --title "Integrate Stripe SDK" \
665
+ --agent "@copilot" \
666
+ --seq 1
667
+
668
+ node wbs.js job add wbs-4 \
669
+ --title "Implement payment endpoint" \
670
+ --agent "@claude:sonnet" \
671
+ --seq 2
672
+
673
+ node wbs.js job add wbs-4 \
674
+ --title "Add webhook handler" \
675
+ --agent "@claude:sonnet" \
676
+ --seq 3
677
+
678
+ # 2. Run all jobs
679
+ node wbs.js job run wbs-4
680
+ ```
681
+
682
+ **Suppose job-2 fails:**
683
+
684
+ ```
685
+ [WBS] Running job: Implement payment endpoint
686
+ [WBS] Agent: @claude:sonnet
687
+ --------------------------------------------------
688
+ Error: Missing API key configuration
689
+ --------------------------------------------------
690
+ [WBS] Job failed: Implement payment endpoint
691
+ ```
692
+
693
+ ```bash
694
+ # 3. Check which jobs failed
695
+ node wbs.js job list wbs-4 --json | jq '.[] | select(.status=="failed")'
696
+ ```
697
+
698
+ **Output:**
699
+ ```json
700
+ {
701
+ "id": "job-2",
702
+ "wbs_id": "wbs-4",
703
+ "title": "Implement payment endpoint",
704
+ "status": "failed",
705
+ "agent": "@claude:sonnet",
706
+ "seq": 2
707
+ }
708
+ ```
709
+
710
+ ```bash
711
+ # 4. Review execution history
712
+ node wbs.js exec list job-2
713
+ ```
714
+
715
+ **Output:**
716
+ ```
717
+ [INFO] Executions for job-2
718
+
719
+ | Status | ID | PID | Start | End | Code |
720
+ |--------|---------|-------|---------------------|---------------------|------|
721
+ | [BAD] | exec-2 | 45678 | 2025-12-18 09:15:00 | 2025-12-18 09:18:00 | 1 |
722
+ ```
723
+
724
+ ```bash
725
+ # 5. Fix the issue (add environment variable or update job description)
726
+ node wbs.js job update job-2 \
727
+ --desc "Implement payment endpoint. Use STRIPE_API_KEY from .env file. Handle both test and production modes."
728
+
729
+ # 6. Retry the failed job
730
+ node wbs.js job retry job-2
731
+ ```
732
+
733
+ **Output:**
734
+ ```
735
+ [WBS] Retrying job: Implement payment endpoint
736
+ [WBS] Running job: Implement payment endpoint
737
+ [WBS] Agent: @claude:sonnet
738
+ [WBS] Timeout: 30 minutes
739
+ --------------------------------------------------
740
+ [Agent output...]
741
+ --------------------------------------------------
742
+ [WBS] Job completed: Implement payment endpoint
743
+
744
+ {
745
+ "success": true,
746
+ "execId": "exec-5"
747
+ }
748
+ ```
749
+
750
+ ```bash
751
+ # 7. Continue with remaining jobs
752
+ node wbs.js job run wbs-4
753
+ ```
754
+
755
+ **Final status:**
756
+ ```
757
+ [INFO] Payment API Integration (wbs-4)
758
+ Status: completed | Progress: 100% (3/3)
759
+
760
+ Jobs:
761
+ | Status | # | ID | Task | Status |
762
+ |--------|----|----|--------------------------|-----------|
763
+ | [OK] | 1 | job-1 | Integrate Stripe SDK | completed |
764
+ | [OK] | 2 | job-2 | Implement payment endpoint| completed |
765
+ | [OK] | 3 | job-3 | Add webhook handler | completed |
766
+ ```
767
+
768
+ **Batch retry all failed jobs:**
769
+ ```bash
770
+ # Find and retry all failed jobs in a project
771
+ for job in $(node wbs.js job list wbs-4 --json | jq -r '.[] | select(.status=="failed") | .id'); do
772
+ echo "Retrying $job..."
773
+ node wbs.js job retry $job
774
+ done
775
+ ```
776
+
777
+ ---
778
+
779
+ ### Example 5: Complex Multi-Agent Coordination
780
+
781
+ Distribute work across different AI agents based on their strengths.
782
+
783
+ **Scenario**: Build a full-stack feature with frontend, backend, and tests
784
+
785
+ ```bash
786
+ # 1. Create project
787
+ node wbs.js create "User Profile Feature"
788
+
789
+ # 2. Add jobs with appropriate agent selection
790
+ # Backend work - @claude:sonnet for complex logic
791
+ node wbs.js job add wbs-5 \
792
+ --title "Design User Profile data model" \
793
+ --agent "@claude:sonnet" \
794
+ --seq 1 \
795
+ --desc "Create schema with fields: avatar, bio, social_links, preferences"
796
+
797
+ # Implementation - @copilot for straightforward coding
798
+ node wbs.js job add wbs-5 \
799
+ --title "Implement profile CRUD API" \
800
+ --agent "@copilot" \
801
+ --seq 2 \
802
+ --desc "REST endpoints for profile operations with validation"
803
+
804
+ # Complex architecture - @claude:opus for advanced decisions
805
+ node wbs.js job add wbs-5 \
806
+ --title "Design avatar upload system" \
807
+ --agent "@claude:opus" \
808
+ --seq 3 \
809
+ --desc "S3 integration with image processing, CDN, and caching strategy"
810
+
811
+ # Implementation again
812
+ node wbs.js job add wbs-5 \
813
+ --title "Implement avatar upload" \
814
+ --agent "@copilot" \
815
+ --seq 4 \
816
+ --desc "File upload endpoint with S3 SDK and image optimization"
817
+
818
+ # Frontend - @claude:sonnet for React components
819
+ node wbs.js job add wbs-5 \
820
+ --title "Create profile edit form" \
821
+ --agent "@claude:sonnet" \
822
+ --seq 5 \
823
+ --desc "React component with form validation and avatar preview"
824
+
825
+ # Testing - @copilot excels at test generation
826
+ node wbs.js job add wbs-5 \
827
+ --title "Write comprehensive tests" \
828
+ --agent "@copilot" \
829
+ --seq 6 \
830
+ --desc "Unit tests for API, integration tests, and React Testing Library tests"
831
+
832
+ # 3. Run the entire pipeline
833
+ node wbs.js job run wbs-5
834
+ ```
835
+
836
+ **Agent selection rationale:**
837
+ - `@claude:sonnet`: Complex logic, architecture, React components
838
+ - `@claude:opus`: Very complex architectural decisions
839
+ - `@copilot`: Straightforward implementation, test generation
840
+ - `@gemini`: Performance optimization, data analysis (not shown here)
841
+
842
+ ---
843
+
844
+ ### Example 6: Working with Detail Documents
845
+
846
+ Use detail documents to provide comprehensive context to all jobs.
847
+
848
+ ```bash
849
+ # 1. Create project with detail document
850
+ node wbs.js create "E-commerce Checkout Flow" --detail ./docs/checkout-spec.md
851
+
852
+ # The system creates: skills/wbs/details/wbs-6-detail.md
853
+ ```
854
+
855
+ **Edit the detail document:**
856
+
857
+ ```bash
858
+ # Edit skills/wbs/details/wbs-6-detail.md
859
+ ```
860
+
861
+ **Content:**
862
+ ```markdown
863
+ # E-commerce Checkout Flow
864
+
865
+ ## Overview
866
+ Implement a secure checkout process for our e-commerce platform.
867
+
868
+ ## Requirements
869
+
870
+ ### Functional Requirements
871
+ 1. Multi-step checkout (cart -> shipping -> payment -> confirmation)
872
+ 2. Address validation with autocomplete
873
+ 3. Multiple payment methods (credit card, PayPal)
874
+ 4. Order summary with promo codes
875
+ 5. Email confirmation
876
+
877
+ ### Technical Requirements
878
+ - Payment processing via Stripe
879
+ - Address validation via Google Maps API
880
+ - Session management for cart persistence
881
+ - Transactional email via SendGrid
882
+
883
+ ### Security
884
+ - PCI compliance for credit card handling
885
+ - HTTPS only
886
+ - CSRF protection
887
+ - Rate limiting on payment endpoints
888
+
889
+ ### Performance
890
+ - Checkout flow should complete in < 3 seconds
891
+ - Optimize for mobile devices
892
+
893
+ ## References
894
+ - [Stripe API Docs](https://stripe.com/docs/api)
895
+ - [Design Mockups](./figma-link)
896
+ ```
897
+
898
+ **Add jobs:**
899
+ ```bash
900
+ node wbs.js job add wbs-6 \
901
+ --title "Implement multi-step form navigation" \
902
+ --agent "@claude:sonnet" \
903
+ --seq 1
904
+
905
+ node wbs.js job add wbs-6 \
906
+ --title "Integrate Stripe payment" \
907
+ --agent "@copilot" \
908
+ --seq 2
909
+
910
+ # ... more jobs
911
+ ```
912
+
913
+ **When jobs run, they automatically receive the detail document content as context.**
914
+
915
+ ---
916
+
917
+ ### Example 7: Monitoring and JSON Output
918
+
919
+ Automate WBS monitoring and integrate with other tools.
920
+
921
+ **Check project status programmatically:**
922
+ ```bash
923
+ # Get JSON output for scripting
924
+ node wbs.js status wbs-1 --json | jq '.summary'
925
+ ```
926
+
927
+ **Output:**
928
+ ```json
929
+ {
930
+ "total_jobs": 4,
931
+ "completed": 4,
932
+ "failed": 0,
933
+ "pending": 0,
934
+ "running": 0,
935
+ "progress": 100
936
+ }
937
+ ```
938
+
939
+ **Create a monitoring script:**
940
+ ```bash
941
+ #!/bin/bash
942
+ # monitor-wbs.sh
943
+
944
+ WBS_ID="wbs-7"
945
+
946
+ while true; do
947
+ clear
948
+ echo "======================================="
949
+ echo " WBS Monitor - $WBS_ID"
950
+ echo "======================================="
951
+
952
+ node wbs.js status $WBS_ID
953
+
954
+ PROGRESS=$(node wbs.js status $WBS_ID --json | jq -r '.summary.progress')
955
+
956
+ if [ "$PROGRESS" -eq 100 ]; then
957
+ echo ""
958
+ echo "[OK] Project complete!"
959
+ break
960
+ fi
961
+
962
+ echo ""
963
+ echo "[WAIT] Checking again in 60 seconds..."
964
+ sleep 60
965
+ done
966
+ ```
967
+
968
+ **Run monitor:**
969
+ ```bash
970
+ chmod +x monitor-wbs.sh
971
+ ./monitor-wbs.sh
972
+ ```
973
+
974
+ **Export jobs to CSV:**
975
+ ```bash
976
+ # Export job list
977
+ echo "ID,Title,Status,Agent,Seq" > jobs-export.csv
978
+ node wbs.js job list wbs-1 --json | \
979
+ jq -r '.[] | [.id,.title,.status,.agent,.seq] | @csv' >> jobs-export.csv
980
+ ```
981
+
982
+ **Check specific job execution history:**
983
+ ```bash
984
+ # List all executions for a job
985
+ node wbs.js exec list job-5 --json | jq '.'
986
+ ```
987
+
988
+ ---
989
+
990
+ ### Example 8: Recovering from Interruptions
991
+
992
+ Handle scenarios where execution is interrupted.
993
+
994
+ **Scenario**: Long-running project interrupted by system crash
995
+
996
+ ```bash
997
+ # 1. Check current status
998
+ node wbs.js list
999
+ ```
1000
+
1001
+ **Output:**
1002
+ ```
1003
+ [INFO] WBS Projects (3)
1004
+
1005
+ | ID | Title | Status | Progress |
1006
+ |-------|-----------------------|----------|----------|
1007
+ | wbs-1 | Todo REST API | completed| 100% 4/4 |
1008
+ | wbs-2 | Bug Fixes | running | 50% 2/4 |
1009
+ | wbs-3 | Refactoring | planning | 0% 0/5 |
1010
+ ```
1011
+
1012
+ ```bash
1013
+ # 2. Check which jobs were running
1014
+ node wbs.js status wbs-2
1015
+ ```
1016
+
1017
+ **Output:**
1018
+ ```
1019
+ [INFO] Bug Fixes (wbs-2)
1020
+ Status: running | Progress: 50% (2/4)
1021
+
1022
+ Jobs:
1023
+ | Status | # | ID | Task | Status |
1024
+ |--------|----|----|---------------|-----------|
1025
+ | [OK] | 1 | job-1 | Fix bug #123 | completed |
1026
+ | [OK] | 2 | job-2 | Fix bug #124 | completed |
1027
+ | [~] | 3 | job-3 | Fix bug #125 | running |
1028
+ | [ ] | 4 | job-4 | Fix bug #126 | pending |
1029
+ ```
1030
+
1031
+ ```bash
1032
+ # 3. Check if the running job actually completed
1033
+ node wbs.js exec list job-3
1034
+ ```
1035
+
1036
+ **If the execution failed or timed out:**
1037
+ ```
1038
+ | Status | ID | PID | Start | End | Code |
1039
+ |--------|---------|-------|---------------------|---------------------|------|
1040
+ | [BAD] | exec-7 | 23456 | 2025-12-18 10:30:00 | N/A (timeout) | -1 |
1041
+ ```
1042
+
1043
+ ```bash
1044
+ # 4. Reset the job and retry
1045
+ node wbs.js job update job-3 --status pending
1046
+ node wbs.js job retry job-3
1047
+
1048
+ # 5. Continue with remaining jobs
1049
+ node wbs.js job run wbs-2
1050
+ ```
1051
+
1052
+ ---
1053
+
1054
+ ### Summary: Quick Command Reference
1055
+
1056
+ **Basic workflow:**
1057
+ ```bash
1058
+ # Create -> Add -> Run -> Check
1059
+ node wbs.js create "Project Name"
1060
+ node wbs.js job add wbs-X --title "Task" --agent "@agent" --seq N
1061
+ node wbs.js job run wbs-X
1062
+ node wbs.js status wbs-X
1063
+ ```
1064
+
1065
+ **Issue-based workflow:**
1066
+ ```bash
1067
+ node wbs.js create "Bug Fixes"
1068
+ node wbs.js job add wbs-X --title "Fix bug" --agent "@agent" --issue 123
1069
+ node wbs.js job run wbs-X
1070
+ ```
1071
+
1072
+ **Step-by-step workflow:**
1073
+ ```bash
1074
+ node wbs.js job next wbs-X # Run one job
1075
+ # Review changes...
1076
+ node wbs.js job next wbs-X # Run next
1077
+ ```
1078
+
1079
+ **Handle failures (job-id or slug):**
1080
+ ```bash
1081
+ node wbs.js job list wbs-X --json | jq '.[] | select(.status=="failed")'
1082
+ node wbs.js job update wbs-X-Y --desc "Updated instructions" # by slug
1083
+ node wbs.js job retry wbs-X-Y # by slug
1084
+ node wbs.js job retry job-Y # by job-id
1085
+ ```
1086
+
1087
+ **Monitoring:**
1088
+ ```bash
1089
+ node wbs.js list
1090
+ node wbs.js status wbs-X
1091
+ node wbs.js status wbs-X --json | jq '.summary'
1092
+ ```
1093
+
1094
+ For more examples, see:
1095
+ - [EXAMPLE.md](./EXAMPLE.md) - Korean language detailed walkthrough
1096
+ - [job-management.md](./job-management.md) - Job-specific examples and patterns
1097
+
1098
+ ## Usage in Coordinator Agent
1099
+
1100
+ The coordinator agent uses this skill programmatically:
1101
+
1102
+ ```javascript
1103
+ const wbs = require('./wbs.js');
1104
+
1105
+ // 1. Create project
1106
+ const id = wbs.create('User Authentication Implementation');
1107
+
1108
+ // 2. Add jobs (AI decomposed)
1109
+ wbs.addJob(id, { title: 'Design User model', agent: '@claude:sonnet', seq: 1 });
1110
+ wbs.addJob(id, { title: 'Implement login API', agent: '@copilot', seq: 2 });
1111
+ wbs.addJob(id, { title: 'Write tests', agent: '@claude:sonnet', seq: 3 });
1112
+
1113
+ // 3. Execute
1114
+ await wbs.run(id);
1115
+
1116
+ // 4. Check status
1117
+ console.log(wbs.status(id));
1118
+ ```
1119
+
1120
+ ## Job Status Flow
1121
+
1122
+ ```
1123
+ pending -> running -> completed
1124
+ -> failed
1125
+ ```
1126
+
1127
+ ## Key Design Decisions
1128
+
1129
+ 1. **AI makes intelligent decisions** - Complexity analysis, job decomposition
1130
+ 2. **Code handles state only** - wbs.js does DB CRUD + worker execution
1131
+ 3. **30-minute timeboxing** - Each job is 15-45 minutes
1132
+ 4. **Start simple, improve iteratively** - MVP first
1133
+
1134
+ ## API Reference
1135
+
1136
+ ### Project Management
1137
+
1138
+ #### `wbs.create(title, options?)`
1139
+ Create a new WBS project. Returns project ID.
1140
+ - `options.detailPath`: Path to detail document (auto-created if not specified)
1141
+
1142
+ #### `wbs.list()`
1143
+ List all WBS projects.
1144
+
1145
+ #### `wbs.status(wbsId)`
1146
+ Get project and all jobs status.
1147
+
1148
+ #### `wbs.delete(wbsId)`
1149
+ Delete a project and all associated jobs/executions.
1150
+
1151
+ ### Job Management
1152
+
1153
+ #### `wbs.addJob(wbsId, { title, description?, agent, seq?, issue_number? })`
1154
+ Add a job to the project. Returns job ID.
1155
+ - `title`: Job title (short name)
1156
+ - `description`: Detailed instructions for the agent
1157
+ - `agent`: Worker agent mention (e.g., `@crewx_claude_dev`)
1158
+ - `seq`: Execution order (default: 0)
1159
+ - `issue_number`: Related GitHub issue number
1160
+
1161
+ #### `wbs.getNextJob(wbsId)`
1162
+ Get the next pending job. Returns job object or null.
1163
+
1164
+ #### `wbs.updateJob(jobId, status)`
1165
+ Update job status. Status: `pending`, `running`, `completed`, `failed`.
1166
+
1167
+ #### `wbs.runWorker(job)`
1168
+ Execute a single worker. Returns `{ success, error?, execId }`.
1169
+
1170
+ #### `wbs.run(wbsId)`
1171
+ Execute all pending jobs sequentially.
1172
+
1173
+ ### Execution Management
1174
+
1175
+ #### `wbs.createExecution(jobId, pid)`
1176
+ Create a new execution record. Returns execution ID.
1177
+
1178
+ #### `wbs.updateExecution(execId, status, options?)`
1179
+ Update execution status.
1180
+ - `options.exitCode`: Process exit code
1181
+ - `options.error`: Error message
1182
+
1183
+ #### `wbs.getExecution(execId)`
1184
+ Get execution by ID.
1185
+
1186
+ #### `wbs.listExecutions(jobId)`
1187
+ List all executions for a job.
1188
+
1189
+ #### `wbs.killExecution(execId)`
1190
+ Kill a running execution. Returns boolean success.
1191
+
1192
+ #### `wbs.getRunningExecutions()`
1193
+ Get all currently running executions.
1194
+
1195
+ ## Related Documentation
1196
+
1197
+ - [WBS Skill Spec](/docs/cto/designs/wbs-skill-spec.md)
1198
+ - [CrewX CLI Documentation](/packages/cli/AGENTS.md)