npm - @crewx/wbs - Versions diffs - 0.1.6 → 0.1.8 - Mend

@crewx/wbs 0.1.6 → 0.1.8

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

package/SKILL.md CHANGED Viewed

@@ -1,1198 +1,1198 @@
----
-name: crewx/wbs
-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.
-metadata:
-  version: 0.3.0
-  built-in: true
----
-# WBS Skill
-Provides state management and worker execution for Work Breakdown Structure based task decomposition.
-## Core Principle
-**System provides state management, AI agent makes intelligent decisions.**
-```
-User Request
-     |
-     v
-+-----------------------------------------------------+
-|  Coordinator Agent (with WBS skill)                  |
-|  - Analyze request (AI judgment)                     |
-|  - Decompose into 30-min Jobs (AI judgment)          |
-|  - Execute workers: crewx x "@agent action"          |
-|  - Track state: wbs.js                               |
-+-----------------------------------------------------+
-     |
-     +---------------+--------------+
-     v               v              v
-+---------+    +---------+    +---------+
-| Worker1 |    | Worker2 |    | Worker3 |
-| @claude |    | @gemini |    | @copilot|
-+---------+    +---------+    +---------+
-```
-## What is WBS Skill?
-The WBS (Work Breakdown Structure) skill is a **project management system for complex AI-driven tasks**. It enables coordinator agents to:
-1. **Decompose complex tasks** into manageable 30-minute jobs
-2. **Track progress** with state management (pending -> running -> completed/failed)
-3. **Coordinate multiple agents** by assigning different jobs to specialized workers
-4. **Manage context** through detail documents and structured workflow
-5. **Execute in parallel** by distributing jobs across multiple worker agents
-### Key Characteristics
-- **Structured Approach**: Projects are broken down into jobs with clear status tracking
-- **Time-Boxed Execution**: Each job targets 15-45 minutes (optimal: 25-30 min)
-- **Multi-Agent Coordination**: Different jobs can be assigned to different AI agents
-- **State Persistence**: All project data, jobs, and execution history are tracked in `.wbs-data.json`
-- **Automated Workflow**: Git branching, PR templates, and issue tracking integration
-- **Job Slug System**: Jobs are identified by intuitive slugs (`wbs-5-1`, `wbs-5-2`) computed from `wbs_id + seq`
-- **Auto-generated Detail Files**: `job add` automatically generates/updates `wbs-details/wbs-{N}-detail.md` with job metadata
-## Job Slug System
-Each job gets a **slug** computed from its WBS ID and sequence number: `wbs-{N}-{seq}`
-| Internal ID | Slug | Meaning |
-|------------|------|---------|
-| `job-15` | `wbs-5-1` | 1st Job of WBS-5 |
-| `job-16` | `wbs-5-2` | 2nd Job of WBS-5 |
-| `job-17` | `wbs-5-3` | 3rd Job of WBS-5 |
-- Slugs are **computed values** (not stored in DB) -- derived from `wbs_id` + `seq`
-- All commands accepting `<job-id>` also accept `<slug>`: `wbs job update wbs-5-1 --status completed`
-- Git branches use slug naming: `feature/wbs-5-1`
-- Worktree directories align with slug naming
-## When to Use WBS Skill
-### Use WBS When
-Choose WBS for tasks that meet **any** of these criteria:
-- **Complex multi-step tasks** (> 45 minutes total)
-  - Feature implementations spanning multiple files/modules
-  - Large-scale refactoring projects
-  - Bug fix sprints with multiple related issues
-- **30-minute timeboxing needed**
-  - Tasks prone to context loss (LLM "Lost in the Middle" problem)
-  - Work requiring periodic checkpoints and validation
-  - Projects where partial progress needs to be tracked
-- **Parallel execution beneficial**
-  - Jobs that can be distributed across multiple worker agents
-  - Tasks where different agents excel at different subtasks
-  - Work that benefits from concurrent execution
-- **Progress tracking important**
-  - Team collaboration requiring visibility into task status
-  - Projects with external stakeholders needing updates
-  - Work where partial failure recovery is critical
-- **GitHub integration needed**
-  - Tasks linked to GitHub issues
-  - Projects requiring structured PR workflows
-  - Work following standardized git branching strategies
-### Use Direct Delegation When
-Skip WBS for simpler scenarios:
-- Single-step tasks (< 15 minutes)
-- One-off file modifications
-- Quick code analysis or queries
-- Rapid prototyping without tracking needs
-- Tasks with no need for state persistence
-### Decision Flow
-```
-Task received
-    |
-    v
-Expected duration?
-    |
-    +--- < 15 min ----------------------> Direct Delegation
-    |
-    +--- 15-45 min -+- Single step ------> Direct Delegation
-    |               +- Multi-step --------> WBS Skill
-    |
-    +--- > 45 min ----------------------> WBS Skill (required)
-```
-## Use Case Examples
-### 1. Complex Feature Implementation
-**Scenario**: Implement user authentication system
-```bash
-# WBS approach - structured and tracked
-wbs.js create "User Authentication Implementation"
-wbs.js job add wbs-1 --title "Design User model" --agent "@claude:sonnet" --seq 1
-wbs.js job add wbs-1 --title "Implement login API" --agent "@copilot" --seq 2
-wbs.js job add wbs-1 --title "Add JWT handling" --agent "@copilot" --seq 3
-wbs.js job add wbs-1 --title "Write unit tests" --agent "@claude:sonnet" --seq 4
-wbs.js job run wbs-1
-```
-**Why WBS**: Multi-step process, multiple agents, progress tracking needed
-### 2. Bug Fix Sprint
-**Scenario**: Fix multiple related authentication bugs
-```bash
-# WBS approach - organized issue resolution
-wbs.js create "Bug Fix Sprint"
-wbs.js job add wbs-2 --title "Fix login bug" --agent "@claude" --issue 42 --seq 1
-wbs.js job add wbs-2 --title "Fix session timeout" --agent "@claude" --issue 43 --seq 2
-wbs.js job add wbs-2 --title "Fix password reset" --agent "@claude" --issue 44 --seq 3
-wbs.js job run wbs-2
-```
-**Why WBS**: Multiple issues, GitHub integration, failure recovery important
-### 3. Large Refactoring
-**Scenario**: Refactor API layer across multiple modules
-```bash
-# WBS approach - context preservation across modules
-wbs.js create "API Refactoring"
-wbs.js job add wbs-3 --title "Refactor auth module" --agent "@claude" --seq 1
-wbs.js job add wbs-3 --title "Refactor user module" --agent "@claude" --seq 2
-wbs.js job add wbs-3 --title "Update tests" --agent "@copilot" --seq 3
-wbs.js job run wbs-3
-```
-**Why WBS**: Context preservation critical, step-by-step validation needed
-### 4. Simple Code Fix (No WBS)
-**Scenario**: Fix a typo in documentation
-```bash
-# Direct delegation - immediate execution
-crewx x "@claude Fix typo in README.md line 42"
-```
-**Why Direct**: Single-step, < 15 minutes, no tracking needed
-## 30-Minute Timeboxing
-| Category | Time | Description |
-|----------|------|-------------|
-| Minimum | 15 min | Below this -> don't separate as Job |
-| Optimal | 25-30 min | Target duration |
-| Maximum | 45 min | Above this -> re-decompose |
-**Rationale**: LLM context limits (Lost in the Middle, Context Rot) + Pomodoro Technique
-## WARNING: Job Description Template (MANDATORY)
-**All Jobs must follow the template below.** Vague Job Descriptions are a leading cause of incomplete work.
-### Template
-```markdown
-**Deliverables:**
-1. path/to/file1.tsx - description
-2. path/to/file2.ts - description
-3. Modify existing file: path/to/existing.tsx
-**Done Criteria:**
-- [ ] Verify component rendering
-- [ ] Verify store integration works
-- [ ] Verify route addition and navigation
-**References:**
-- docs/ui-screens/screens/XX.md
-- Wireframe/design links
-```
-### Usage Example
-```bash
-# [BAD] BAD - Vague Job Description
-node wbs.js job add wbs-1 \
-  --title "Agent settings screen" \
-  --desc "Display crewx.yaml agent list. Model/provider/prompt editing UI." \
-  --agent "@launcher_gemini_dev"
-# [OK] GOOD - Clear deliverables and done criteria
-node wbs.js job add wbs-1 \
-  --title "Agent settings screen" \
-  --desc "**Deliverables:**
-1. src/renderer/components/AgentConfig/AgentConfigPage.tsx - Agent list page
-2. src/renderer/components/AgentConfig/AgentEditModal.tsx - Edit modal
-3. src/renderer/App.tsx - Add /agents route
-4. src/renderer/components/Layout/Sidebar.tsx - Add menu item
-**Done Criteria:**
-- [ ] Agent list displays when navigating to /agents
-- [ ] Edit modal opens on button click
-- [ ] Changes saved to crewx.yaml on save
-**References:** docs/ui-screens/screens/03-agent.md" \
-  --agent "@launcher_gemini_dev"
-```
-### Why Is This Mandatory?
-| Problem | Vague Job Description | With Template |
-|---------|----------------------|---------------|
-| **Scope interpretation** | Agent interprets arbitrarily | Clear file list |
-| **Completion judgment** | Manual "done" marking | Checklist verification |
-| **Preventing omissions** | Only Store without UI | All deliverables specified |
-| **Review ease** | Unclear what to verify | Checklist-based review |
-### Integration Test Job Template
-Integration test Jobs must specify verification items in detail:
-```bash
-node wbs.js job add wbs-1 \
-  --title "Integration test" \
-  --desc "**Verification Scenarios:**
-1. Onboarding -> Preset selection -> Installation complete
-2. Dashboard -> Agent list displays
-3. Agent settings -> Edit -> Save
-**Verification Methods:**
-- [ ] Manual execution of each scenario
-- [ ] Screenshot capture (using skills/playwright-python)
-- [ ] Error log inspection
-**Pass Criteria:**
-- All scenarios work correctly
-- No console errors" \
-  --agent "@launcher_codex_dev"
-```
-## Installation
-```bash
-cd skills/wbs
-npm install
-```
-Requires Node.js 16+.
-## Commands Reference
-### Project Management Commands
-| Command | Syntax | Description |
-|---------|--------|-------------|
-| **create** | `wbs.js create "Title" [--detail path]` | Create new WBS project with sequential ID (wbs-1, wbs-2, ...) |
-| **list** | `wbs.js list [--json]` | List all projects with status and progress |
-| **status** | `wbs.js status <wbs-id> [--json]` | Get detailed project info including all jobs and summary stats |
-| **delete** | `wbs.js delete <wbs-id>` | Delete project and all associated jobs/executions (irreversible) |
-### Job Management Commands
-| Command | Syntax | Description |
-|---------|--------|-------------|
-| **job add** | `wbs.js job add <wbs-id> --title "Title" --agent "@agent" [options]` | Add new job to project. Options: `--desc`, `--seq`, `--issue` |
-| **job list** | `wbs.js job list <wbs-id> [--json]` | List all jobs ordered by sequence number |
-| **job update** | `wbs.js job update <job-id\|slug> [options]` | Update job properties. Options: `--status`, `--title`, `--desc`, `--agent`, `--seq`, `--issue` |
-| **job run** | `wbs.js job run <wbs-id>` | Execute all pending jobs sequentially (30-min timeout each) |
-| **job next** | `wbs.js job next <wbs-id>` | Execute only the next pending job (manual step-by-step) |
-| **job retry** | `wbs.js job retry <job-id\|slug>` | Retry a failed or completed job |
-### Execution Management Commands
-| Command | Syntax | Description |
-|---------|--------|-------------|
-| **exec list** | `wbs.js exec list <job-id\|slug> [--json]` | List execution history for a job |
-| **exec status** | `wbs.js exec status <exec-id> [--json]` | Get detailed execution info |
-| **exec kill** | `wbs.js exec kill <exec-id>` | Kill a running execution |
-| **exec running** | `wbs.js exec running [--json]` | List all currently running executions |
-### Coordinator Commands (Natural Language)
-| Command | Syntax | Description |
-|---------|--------|-------------|
-| **q** | `wbs.js q "question"` | Ask coordinator a question (via `@wbs_coordinator`) |
-| **x** | `wbs.js x "request"` | Request coordinator to execute an action |
-### Daemon Commands (Background Scheduler)
-| Command | Syntax | Description |
-|---------|--------|-------------|
-| **daemon start** | `wbs.js daemon start` | Start background scheduler |
-| **daemon stop** | `wbs.js daemon stop` | Stop running daemon |
-| **daemon status** | `wbs.js daemon status` | Check daemon status |
-| **daemon tick** | `wbs.js daemon tick` | Manual tick for testing |
-### Common Usage Patterns
-```bash
-# Create and run a complete project
-wbs.js create "User Authentication"
-wbs.js job add wbs-1 --title "Design schema" --agent "@claude:sonnet" --seq 1
-wbs.js job add wbs-1 --title "Implement API" --agent "@copilot" --seq 2
-wbs.js job add wbs-1 --title "Write tests" --agent "@claude:sonnet" --seq 3
-wbs.js job run wbs-1
-# Check progress
-wbs.js status wbs-1
-# Handle failures (use job-id or slug)
-wbs.js job list wbs-1 --json | jq '.[] | select(.status=="failed")'
-wbs.js job retry wbs-1-3      # by slug
-wbs.js job retry job-5         # by job-id
-# Issue-based workflow
-wbs.js job add wbs-2 --title "Fix bug" --agent "@claude" --issue 42
-```
-### Output Formats
-- **Default**: Human-readable tables with emoji status icons
-- **--json**: Machine-parseable JSON for scripting and automation
-For detailed command documentation, see:
-- [COMMANDS.md](./COMMANDS.md) - Complete project commands reference
-- [job-management.md](./job-management.md) - Comprehensive job management guide
-## Practical Usage Examples
-This section provides comprehensive real-world examples of using the WBS skill effectively.
-### Example 1: Simple Workflow (Create -> Add Jobs -> Run)
-The most basic WBS workflow involves creating a project, adding jobs, and running them sequentially.
-**Scenario**: Build a simple REST API for a todo application
-```bash
-# 1. Create the project
-node wbs.js create "Todo REST API"
-```
-**Expected output:**
-```json
-{
-  "id": "wbs-1",
-  "title": "Todo REST API",
-  "status": "planning",
-  "detailPath": "skills/wbs/details/wbs-1-detail.md",
-  "created_at": "2025-12-18T08:00:00.000Z"
-}
-```
-```bash
-# 2. Add jobs for implementation
-node wbs.js job add wbs-1 \
-  --title "Design database schema" \
-  --agent "@claude:sonnet" \
-  --seq 1 \
-  --desc "Create SQLite schema for todos table with id, title, completed, created_at fields"
-node wbs.js job add wbs-1 \
-  --title "Implement CRUD endpoints" \
-  --agent "@copilot" \
-  --seq 2 \
-  --desc "Create Express routes: GET /todos, POST /todos, PUT /todos/:id, DELETE /todos/:id"
-node wbs.js job add wbs-1 \
-  --title "Add input validation" \
-  --agent "@claude:sonnet" \
-  --seq 3 \
-  --desc "Implement request validation middleware using express-validator"
-node wbs.js job add wbs-1 \
-  --title "Write integration tests" \
-  --agent "@copilot" \
-  --seq 4 \
-  --desc "Create test suite covering all CRUD operations using supertest"
-```
-```bash
-# 3. Review the planned jobs
-node wbs.js status wbs-1
-```
-**Expected output:**
-```
-[INFO] Todo REST API (wbs-1)
-   Status: planning | Progress: 0% (0/4)
-   Detail: skills/wbs/details/wbs-1-detail.md
-   Jobs:
-   | Status | #  | Slug      | ID    | Task                      | Agent           |
-   |--------|----|-----------|-------|--------------------------|-----------------|
-   | [ ]  | 1  | wbs-1-1   | job-1 | Design database schema    | @claude:sonnet  |
-   | [ ]  | 2  | wbs-1-2   | job-2 | Implement CRUD endpoints  | @copilot        |
-   | [ ]  | 3  | wbs-1-3   | job-3 | Add input validation      | @claude:sonnet  |
-   | [ ]  | 4  | wbs-1-4   | job-4 | Write integration tests   | @copilot        |
-```
-```bash
-# 4. Run all jobs
-node wbs.js job run wbs-1
-```
-**Expected output:**
-```
-==================================================
-[WBS] Starting project: Todo REST API
-==================================================
-[WBS] Running job: Design database schema
-[WBS] Agent: @claude:sonnet
-[WBS] Description: Create SQLite schema for todos table...
-[WBS] Timeout: 30 minutes
---------------------------------------------------
-[Agent executes and produces output...]
---------------------------------------------------
-[WBS] Job completed: Design database schema
-[WBS] Running job: Implement CRUD endpoints
-[WBS] Agent: @copilot
-[WBS] Timeout: 30 minutes
---------------------------------------------------
-[Agent executes and produces output...]
---------------------------------------------------
-[WBS] Job completed: Implement CRUD endpoints
-[... continues for remaining jobs ...]
-==================================================
-[WBS] Project completed: Todo REST API
-[WBS] Completed: 4, Failed: 0
-==================================================
-```
-```bash
-# 5. Verify completion
-node wbs.js status wbs-1
-```
-**Final output:**
-```
-[INFO] Todo REST API (wbs-1)
-   Status: completed | Progress: 100% (4/4)
-   Detail: skills/wbs/details/wbs-1-detail.md
-   Jobs:
-   | Status | #  | Slug      | ID    | Task                      | Agent           | Status    |
-   |--------|----|-----------|-------|--------------------------|-----------------|-----------|
-   | [OK]   | 1  | wbs-1-1   | job-1 | Design database schema    | @claude:sonnet  | completed |
-   | [OK]   | 2  | wbs-1-2   | job-2 | Implement CRUD endpoints  | @copilot        | completed |
-   | [OK]   | 3  | wbs-1-3   | job-3 | Add input validation      | @claude:sonnet  | completed |
-   | [OK]   | 4  | wbs-1-4   | job-4 | Write integration tests   | @copilot        | completed |
-```
----
-### Example 2: Issue-Based Workflow
-Use WBS to manage multiple GitHub issues systematically.
-**Scenario**: Fix authentication-related bugs tracked in GitHub
-```bash
-# 1. Create project for bug fixes
-node wbs.js create "Authentication Bug Fixes"
-```
-**Output:**
-```json
-{
-  "id": "wbs-2",
-  "title": "Authentication Bug Fixes",
-  "status": "planning"
-}
-```
-```bash
-# 2. Add jobs linked to GitHub issues
-node wbs.js job add wbs-2 \
-  --title "Fix: Login fails with special characters in password" \
-  --agent "@claude:sonnet" \
-  --issue 123 \
-  --seq 1
-node wbs.js job add wbs-2 \
-  --title "Fix: Session timeout not working" \
-  --agent "@claude:sonnet" \
-  --issue 124 \
-  --seq 2
-node wbs.js job add wbs-2 \
-  --title "Fix: Password reset email not sent" \
-  --agent "@claude:sonnet" \
-  --issue 125 \
-  --seq 3
-```
-**What happens during execution:**
-When you run `node wbs.js job run wbs-2`, each job receives these instructions:
-```
-## Task Instructions
-Process GitHub Issue #123.
-**Follow your existing development process:**
-1. Check the issue with `gh issue view 123`
-2. Create branch and work
-3. Create PR
-4. Comment results on the issue
-WBS Tracking Info:
-- WBS: wbs-2
-- Job: job-1
-```
-**Advantages:**
-- Automatic issue-branch-PR linking
-- Agent follows its own development workflow
-- Easy progress tracking via GitHub
-- Issue comments document resolution
----
-### Example 3: Step-by-Step Execution
-Execute jobs manually one at a time with review between each step.
-**Scenario**: Refactoring legacy code where each step needs verification
-```bash
-# 1. Create project
-node wbs.js create "Legacy Code Refactoring"
-# 2. Add jobs
-node wbs.js job add wbs-3 \
-  --title "Extract UserService from monolithic controller" \
-  --agent "@claude:opus" \
-  --seq 1 \
-  --desc "Move user-related logic from AppController to new UserService class"
-node wbs.js job add wbs-3 \
-  --title "Add dependency injection" \
-  --agent "@claude:sonnet" \
-  --seq 2 \
-  --desc "Refactor UserService to use constructor injection for database"
-node wbs.js job add wbs-3 \
-  --title "Update unit tests" \
-  --agent "@copilot" \
-  --seq 3 \
-  --desc "Modify tests to work with new UserService architecture"
-node wbs.js job add wbs-3 \
-  --title "Verify integration tests pass" \
-  --agent "@copilot" \
-  --seq 4 \
-  --desc "Run full test suite and fix any integration issues"
-```
-```bash
-# 3. Execute first job only
-node wbs.js job next wbs-3
-```
-**Output:**
-```
-[WBS] Running job: Extract UserService from monolithic controller
-[WBS] Agent: @claude:opus
-[WBS] Timeout: 30 minutes
---------------------------------------------------
-[Agent output...]
---------------------------------------------------
-[WBS] Job completed: Extract UserService from monolithic controller
-{
-  "success": true,
-  "execId": "exec-1"
-}
-```
-```bash
-# 4. Review changes before continuing
-git diff
-npm test
-# 5. If satisfied, run next job
-node wbs.js job next wbs-3
-```
-**Output:**
-```
-[WBS] Running job: Add dependency injection
-[WBS] Agent: @claude:sonnet
-...
-```
-```bash
-# 6. Continue step by step
-node wbs.js status wbs-3  # Check progress
-node wbs.js job next wbs-3  # Run next job
-```
-**Use cases for step-by-step execution:**
-- Code reviews between steps
-- Testing after each change
-- Learning/understanding the codebase
-- High-risk refactoring
-- Debugging job configurations
----
-### Example 4: Handling Failures
-Recover from failed jobs and retry with updated configurations.
-**Scenario**: API implementation where initial attempts fail
-```bash
-# 1. Create project and add jobs
-node wbs.js create "Payment API Integration"
-node wbs.js job add wbs-4 \
-  --title "Integrate Stripe SDK" \
-  --agent "@copilot" \
-  --seq 1
-node wbs.js job add wbs-4 \
-  --title "Implement payment endpoint" \
-  --agent "@claude:sonnet" \
-  --seq 2
-node wbs.js job add wbs-4 \
-  --title "Add webhook handler" \
-  --agent "@claude:sonnet" \
-  --seq 3
-# 2. Run all jobs
-node wbs.js job run wbs-4
-```
-**Suppose job-2 fails:**
-```
-[WBS] Running job: Implement payment endpoint
-[WBS] Agent: @claude:sonnet
---------------------------------------------------
-Error: Missing API key configuration
---------------------------------------------------
-[WBS] Job failed: Implement payment endpoint
-```
-```bash
-# 3. Check which jobs failed
-node wbs.js job list wbs-4 --json | jq '.[] | select(.status=="failed")'
-```
-**Output:**
-```json
-{
-  "id": "job-2",
-  "wbs_id": "wbs-4",
-  "title": "Implement payment endpoint",
-  "status": "failed",
-  "agent": "@claude:sonnet",
-  "seq": 2
-}
-```
-```bash
-# 4. Review execution history
-node wbs.js exec list job-2
-```
-**Output:**
-```
-[INFO] Executions for job-2
-| Status | ID      | PID   | Start               | End                 | Code |
-|--------|---------|-------|---------------------|---------------------|------|
-| [BAD]   | exec-2  | 45678 | 2025-12-18 09:15:00 | 2025-12-18 09:18:00 | 1    |
-```
-```bash
-# 5. Fix the issue (add environment variable or update job description)
-node wbs.js job update job-2 \
-  --desc "Implement payment endpoint. Use STRIPE_API_KEY from .env file. Handle both test and production modes."
-# 6. Retry the failed job
-node wbs.js job retry job-2
-```
-**Output:**
-```
-[WBS] Retrying job: Implement payment endpoint
-[WBS] Running job: Implement payment endpoint
-[WBS] Agent: @claude:sonnet
-[WBS] Timeout: 30 minutes
---------------------------------------------------
-[Agent output...]
---------------------------------------------------
-[WBS] Job completed: Implement payment endpoint
-{
-  "success": true,
-  "execId": "exec-5"
-}
-```
-```bash
-# 7. Continue with remaining jobs
-node wbs.js job run wbs-4
-```
-**Final status:**
-```
-[INFO] Payment API Integration (wbs-4)
-   Status: completed | Progress: 100% (3/3)
-   Jobs:
-   | Status | #  | ID    | Task                      | Status    |
-   |--------|----|----|--------------------------|-----------|
-   | [OK]   | 1  | job-1 | Integrate Stripe SDK      | completed |
-   | [OK]   | 2  | job-2 | Implement payment endpoint| completed |
-   | [OK]   | 3  | job-3 | Add webhook handler       | completed |
-```
-**Batch retry all failed jobs:**
-```bash
-# Find and retry all failed jobs in a project
-for job in $(node wbs.js job list wbs-4 --json | jq -r '.[] | select(.status=="failed") | .id'); do
-  echo "Retrying $job..."
-  node wbs.js job retry $job
-done
-```
----
-### Example 5: Complex Multi-Agent Coordination
-Distribute work across different AI agents based on their strengths.
-**Scenario**: Build a full-stack feature with frontend, backend, and tests
-```bash
-# 1. Create project
-node wbs.js create "User Profile Feature"
-# 2. Add jobs with appropriate agent selection
-# Backend work - @claude:sonnet for complex logic
-node wbs.js job add wbs-5 \
-  --title "Design User Profile data model" \
-  --agent "@claude:sonnet" \
-  --seq 1 \
-  --desc "Create schema with fields: avatar, bio, social_links, preferences"
-# Implementation - @copilot for straightforward coding
-node wbs.js job add wbs-5 \
-  --title "Implement profile CRUD API" \
-  --agent "@copilot" \
-  --seq 2 \
-  --desc "REST endpoints for profile operations with validation"
-# Complex architecture - @claude:opus for advanced decisions
-node wbs.js job add wbs-5 \
-  --title "Design avatar upload system" \
-  --agent "@claude:opus" \
-  --seq 3 \
-  --desc "S3 integration with image processing, CDN, and caching strategy"
-# Implementation again
-node wbs.js job add wbs-5 \
-  --title "Implement avatar upload" \
-  --agent "@copilot" \
-  --seq 4 \
-  --desc "File upload endpoint with S3 SDK and image optimization"
-# Frontend - @claude:sonnet for React components
-node wbs.js job add wbs-5 \
-  --title "Create profile edit form" \
-  --agent "@claude:sonnet" \
-  --seq 5 \
-  --desc "React component with form validation and avatar preview"
-# Testing - @copilot excels at test generation
-node wbs.js job add wbs-5 \
-  --title "Write comprehensive tests" \
-  --agent "@copilot" \
-  --seq 6 \
-  --desc "Unit tests for API, integration tests, and React Testing Library tests"
-# 3. Run the entire pipeline
-node wbs.js job run wbs-5
-```
-**Agent selection rationale:**
-- `@claude:sonnet`: Complex logic, architecture, React components
-- `@claude:opus`: Very complex architectural decisions
-- `@copilot`: Straightforward implementation, test generation
-- `@gemini`: Performance optimization, data analysis (not shown here)
----
-### Example 6: Working with Detail Documents
-Use detail documents to provide comprehensive context to all jobs.
-```bash
-# 1. Create project with detail document
-node wbs.js create "E-commerce Checkout Flow" --detail ./docs/checkout-spec.md
-# The system creates: skills/wbs/details/wbs-6-detail.md
-```
-**Edit the detail document:**
-```bash
-# Edit skills/wbs/details/wbs-6-detail.md
-```
-**Content:**
-```markdown
-# E-commerce Checkout Flow
-## Overview
-Implement a secure checkout process for our e-commerce platform.
-## Requirements
-### Functional Requirements
-1. Multi-step checkout (cart -> shipping -> payment -> confirmation)
-2. Address validation with autocomplete
-3. Multiple payment methods (credit card, PayPal)
-4. Order summary with promo codes
-5. Email confirmation
-### Technical Requirements
-- Payment processing via Stripe
-- Address validation via Google Maps API
-- Session management for cart persistence
-- Transactional email via SendGrid
-### Security
-- PCI compliance for credit card handling
-- HTTPS only
-- CSRF protection
-- Rate limiting on payment endpoints
-### Performance
-- Checkout flow should complete in < 3 seconds
-- Optimize for mobile devices
-## References
-- [Stripe API Docs](https://stripe.com/docs/api)
-- [Design Mockups](./figma-link)
-```
-**Add jobs:**
-```bash
-node wbs.js job add wbs-6 \
-  --title "Implement multi-step form navigation" \
-  --agent "@claude:sonnet" \
-  --seq 1
-node wbs.js job add wbs-6 \
-  --title "Integrate Stripe payment" \
-  --agent "@copilot" \
-  --seq 2
-# ... more jobs
-```
-**When jobs run, they automatically receive the detail document content as context.**
----
-### Example 7: Monitoring and JSON Output
-Automate WBS monitoring and integrate with other tools.
-**Check project status programmatically:**
-```bash
-# Get JSON output for scripting
-node wbs.js status wbs-1 --json | jq '.summary'
-```
-**Output:**
-```json
-{
-  "total_jobs": 4,
-  "completed": 4,
-  "failed": 0,
-  "pending": 0,
-  "running": 0,
-  "progress": 100
-}
-```
-**Create a monitoring script:**
-```bash
-#!/bin/bash
-# monitor-wbs.sh
-WBS_ID="wbs-7"
-while true; do
-  clear
-  echo "======================================="
-  echo "  WBS Monitor - $WBS_ID"
-  echo "======================================="
-  node wbs.js status $WBS_ID
-  PROGRESS=$(node wbs.js status $WBS_ID --json | jq -r '.summary.progress')
-  if [ "$PROGRESS" -eq 100 ]; then
-    echo ""
-    echo "[OK] Project complete!"
-    break
-  fi
-  echo ""
-  echo "[WAIT] Checking again in 60 seconds..."
-  sleep 60
-done
-```
-**Run monitor:**
-```bash
-chmod +x monitor-wbs.sh
-./monitor-wbs.sh
-```
-**Export jobs to CSV:**
-```bash
-# Export job list
-echo "ID,Title,Status,Agent,Seq" > jobs-export.csv
-node wbs.js job list wbs-1 --json | \
-  jq -r '.[] | [.id,.title,.status,.agent,.seq] | @csv' >> jobs-export.csv
-```
-**Check specific job execution history:**
-```bash
-# List all executions for a job
-node wbs.js exec list job-5 --json | jq '.'
-```
----
-### Example 8: Recovering from Interruptions
-Handle scenarios where execution is interrupted.
-**Scenario**: Long-running project interrupted by system crash
-```bash
-# 1. Check current status
-node wbs.js list
-```
-**Output:**
-```
-[INFO] WBS Projects (3)
-| ID    | Title                   | Status    | Progress  |
-|-------|-----------------------|----------|----------|
-| wbs-1 | Todo REST API         | completed| 100% 4/4 |
-| wbs-2 | Bug Fixes             | running  | 50% 2/4  |
-| wbs-3 | Refactoring           | planning | 0% 0/5   |
-```
-```bash
-# 2. Check which jobs were running
-node wbs.js status wbs-2
-```
-**Output:**
-```
-[INFO] Bug Fixes (wbs-2)
-   Status: running | Progress: 50% (2/4)
-   Jobs:
-   | Status | #  | ID    | Task           | Status    |
-   |--------|----|----|---------------|-----------|
-   | [OK]   | 1  | job-1 | Fix bug #123   | completed |
-   | [OK]   | 2  | job-2 | Fix bug #124   | completed |
-   | [~]   | 3  | job-3 | Fix bug #125   | running   |
-   | [ ]  | 4  | job-4 | Fix bug #126   | pending   |
-```
-```bash
-# 3. Check if the running job actually completed
-node wbs.js exec list job-3
-```
-**If the execution failed or timed out:**
-```
-| Status | ID      | PID   | Start               | End                 | Code |
-|--------|---------|-------|---------------------|---------------------|------|
-| [BAD]   | exec-7  | 23456 | 2025-12-18 10:30:00 | N/A (timeout)       | -1   |
-```
-```bash
-# 4. Reset the job and retry
-node wbs.js job update job-3 --status pending
-node wbs.js job retry job-3
-# 5. Continue with remaining jobs
-node wbs.js job run wbs-2
-```
----
-### Summary: Quick Command Reference
-**Basic workflow:**
-```bash
-# Create -> Add -> Run -> Check
-node wbs.js create "Project Name"
-node wbs.js job add wbs-X --title "Task" --agent "@agent" --seq N
-node wbs.js job run wbs-X
-node wbs.js status wbs-X
-```
-**Issue-based workflow:**
-```bash
-node wbs.js create "Bug Fixes"
-node wbs.js job add wbs-X --title "Fix bug" --agent "@agent" --issue 123
-node wbs.js job run wbs-X
-```
-**Step-by-step workflow:**
-```bash
-node wbs.js job next wbs-X  # Run one job
-# Review changes...
-node wbs.js job next wbs-X  # Run next
-```
-**Handle failures (job-id or slug):**
-```bash
-node wbs.js job list wbs-X --json | jq '.[] | select(.status=="failed")'
-node wbs.js job update wbs-X-Y --desc "Updated instructions"  # by slug
-node wbs.js job retry wbs-X-Y                                  # by slug
-node wbs.js job retry job-Y                                    # by job-id
-```
-**Monitoring:**
-```bash
-node wbs.js list
-node wbs.js status wbs-X
-node wbs.js status wbs-X --json | jq '.summary'
-```
-For more examples, see:
-- [EXAMPLE.md](./EXAMPLE.md) - Korean language detailed walkthrough
-- [job-management.md](./job-management.md) - Job-specific examples and patterns
-## Usage in Coordinator Agent
-The coordinator agent uses this skill programmatically:
-```javascript
-const wbs = require('./wbs.js');
-// 1. Create project
-const id = wbs.create('User Authentication Implementation');
-// 2. Add jobs (AI decomposed)
-wbs.addJob(id, { title: 'Design User model', agent: '@claude:sonnet', seq: 1 });
-wbs.addJob(id, { title: 'Implement login API', agent: '@copilot', seq: 2 });
-wbs.addJob(id, { title: 'Write tests', agent: '@claude:sonnet', seq: 3 });
-// 3. Execute
-await wbs.run(id);
-// 4. Check status
-console.log(wbs.status(id));
-```
-## Job Status Flow
-```
-pending -> running -> completed
-                  -> failed
-```
-## Key Design Decisions
-1. **AI makes intelligent decisions** - Complexity analysis, job decomposition
-2. **Code handles state only** - wbs.js does DB CRUD + worker execution
-3. **30-minute timeboxing** - Each job is 15-45 minutes
-4. **Start simple, improve iteratively** - MVP first
-## API Reference
-### Project Management
-#### `wbs.create(title, options?)`
-Create a new WBS project. Returns project ID.
-- `options.detailPath`: Path to detail document (auto-created if not specified)
-#### `wbs.list()`
-List all WBS projects.
-#### `wbs.status(wbsId)`
-Get project and all jobs status.
-#### `wbs.delete(wbsId)`
-Delete a project and all associated jobs/executions.
-### Job Management
-#### `wbs.addJob(wbsId, { title, description?, agent, seq?, issue_number? })`
-Add a job to the project. Returns job ID.
-- `title`: Job title (short name)
-- `description`: Detailed instructions for the agent
-- `agent`: Worker agent mention (e.g., `@crewx_claude_dev`)
-- `seq`: Execution order (default: 0)
-- `issue_number`: Related GitHub issue number
-#### `wbs.getNextJob(wbsId)`
-Get the next pending job. Returns job object or null.
-#### `wbs.updateJob(jobId, status)`
-Update job status. Status: `pending`, `running`, `completed`, `failed`.
-#### `wbs.runWorker(job)`
-Execute a single worker. Returns `{ success, error?, execId }`.
-#### `wbs.run(wbsId)`
-Execute all pending jobs sequentially.
-### Execution Management
-#### `wbs.createExecution(jobId, pid)`
-Create a new execution record. Returns execution ID.
-#### `wbs.updateExecution(execId, status, options?)`
-Update execution status.
-- `options.exitCode`: Process exit code
-- `options.error`: Error message
-#### `wbs.getExecution(execId)`
-Get execution by ID.
-#### `wbs.listExecutions(jobId)`
-List all executions for a job.
-#### `wbs.killExecution(execId)`
-Kill a running execution. Returns boolean success.
-#### `wbs.getRunningExecutions()`
-Get all currently running executions.
-## Related Documentation
-- [WBS Skill Spec](/docs/cto/designs/wbs-skill-spec.md)
-- [CrewX CLI Documentation](/packages/cli/AGENTS.md)
+---
+name: crewx/wbs
+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.
+metadata:
+  version: 0.3.0
+  built-in: true
+---
+# WBS Skill
+Provides state management and worker execution for Work Breakdown Structure based task decomposition.
+## Core Principle
+**System provides state management, AI agent makes intelligent decisions.**
+```
+User Request
+     |
+     v
++-----------------------------------------------------+
+|  Coordinator Agent (with WBS skill)                  |
+|  - Analyze request (AI judgment)                     |
+|  - Decompose into 30-min Jobs (AI judgment)          |
+|  - Execute workers: crewx x "@agent action"          |
+|  - Track state: wbs.js                               |
++-----------------------------------------------------+
+     |
+     +---------------+--------------+
+     v               v              v
++---------+    +---------+    +---------+
+| Worker1 |    | Worker2 |    | Worker3 |
+| @claude |    | @gemini |    | @copilot|
++---------+    +---------+    +---------+
+```
+## What is WBS Skill?
+The WBS (Work Breakdown Structure) skill is a **project management system for complex AI-driven tasks**. It enables coordinator agents to:
+1. **Decompose complex tasks** into manageable 30-minute jobs
+2. **Track progress** with state management (pending -> running -> completed/failed)
+3. **Coordinate multiple agents** by assigning different jobs to specialized workers
+4. **Manage context** through detail documents and structured workflow
+5. **Execute in parallel** by distributing jobs across multiple worker agents
+### Key Characteristics
+- **Structured Approach**: Projects are broken down into jobs with clear status tracking
+- **Time-Boxed Execution**: Each job targets 15-45 minutes (optimal: 25-30 min)
+- **Multi-Agent Coordination**: Different jobs can be assigned to different AI agents
+- **State Persistence**: All project data, jobs, and execution history are tracked in `.wbs-data.json`
+- **Automated Workflow**: Git branching, PR templates, and issue tracking integration
+- **Job Slug System**: Jobs are identified by intuitive slugs (`wbs-5-1`, `wbs-5-2`) computed from `wbs_id + seq`
+- **Auto-generated Detail Files**: `job add` automatically generates/updates `wbs-details/wbs-{N}-detail.md` with job metadata
+## Job Slug System
+Each job gets a **slug** computed from its WBS ID and sequence number: `wbs-{N}-{seq}`
+| Internal ID | Slug | Meaning |
+|------------|------|---------|
+| `job-15` | `wbs-5-1` | 1st Job of WBS-5 |
+| `job-16` | `wbs-5-2` | 2nd Job of WBS-5 |
+| `job-17` | `wbs-5-3` | 3rd Job of WBS-5 |
+- Slugs are **computed values** (not stored in DB) -- derived from `wbs_id` + `seq`
+- All commands accepting `<job-id>` also accept `<slug>`: `wbs job update wbs-5-1 --status completed`
+- Git branches use slug naming: `feature/wbs-5-1`
+- Worktree directories align with slug naming
+## When to Use WBS Skill
+### Use WBS When
+Choose WBS for tasks that meet **any** of these criteria:
+- **Complex multi-step tasks** (> 45 minutes total)
+  - Feature implementations spanning multiple files/modules
+  - Large-scale refactoring projects
+  - Bug fix sprints with multiple related issues
+- **30-minute timeboxing needed**
+  - Tasks prone to context loss (LLM "Lost in the Middle" problem)
+  - Work requiring periodic checkpoints and validation
+  - Projects where partial progress needs to be tracked
+- **Parallel execution beneficial**
+  - Jobs that can be distributed across multiple worker agents
+  - Tasks where different agents excel at different subtasks
+  - Work that benefits from concurrent execution
+- **Progress tracking important**
+  - Team collaboration requiring visibility into task status
+  - Projects with external stakeholders needing updates
+  - Work where partial failure recovery is critical
+- **GitHub integration needed**
+  - Tasks linked to GitHub issues
+  - Projects requiring structured PR workflows
+  - Work following standardized git branching strategies
+### Use Direct Delegation When
+Skip WBS for simpler scenarios:
+- Single-step tasks (< 15 minutes)
+- One-off file modifications
+- Quick code analysis or queries
+- Rapid prototyping without tracking needs
+- Tasks with no need for state persistence
+### Decision Flow
+```
+Task received
+    |
+    v
+Expected duration?
+    |
+    +--- < 15 min ----------------------> Direct Delegation
+    |
+    +--- 15-45 min -+- Single step ------> Direct Delegation
+    |               +- Multi-step --------> WBS Skill
+    |
+    +--- > 45 min ----------------------> WBS Skill (required)
+```
+## Use Case Examples
+### 1. Complex Feature Implementation
+**Scenario**: Implement user authentication system
+```bash
+# WBS approach - structured and tracked
+wbs.js create "User Authentication Implementation"
+wbs.js job add wbs-1 --title "Design User model" --agent "@claude:sonnet" --seq 1
+wbs.js job add wbs-1 --title "Implement login API" --agent "@copilot" --seq 2
+wbs.js job add wbs-1 --title "Add JWT handling" --agent "@copilot" --seq 3
+wbs.js job add wbs-1 --title "Write unit tests" --agent "@claude:sonnet" --seq 4
+wbs.js job run wbs-1
+```
+**Why WBS**: Multi-step process, multiple agents, progress tracking needed
+### 2. Bug Fix Sprint
+**Scenario**: Fix multiple related authentication bugs
+```bash
+# WBS approach - organized issue resolution
+wbs.js create "Bug Fix Sprint"
+wbs.js job add wbs-2 --title "Fix login bug" --agent "@claude" --issue 42 --seq 1
+wbs.js job add wbs-2 --title "Fix session timeout" --agent "@claude" --issue 43 --seq 2
+wbs.js job add wbs-2 --title "Fix password reset" --agent "@claude" --issue 44 --seq 3
+wbs.js job run wbs-2
+```
+**Why WBS**: Multiple issues, GitHub integration, failure recovery important
+### 3. Large Refactoring
+**Scenario**: Refactor API layer across multiple modules
+```bash
+# WBS approach - context preservation across modules
+wbs.js create "API Refactoring"
+wbs.js job add wbs-3 --title "Refactor auth module" --agent "@claude" --seq 1
+wbs.js job add wbs-3 --title "Refactor user module" --agent "@claude" --seq 2
+wbs.js job add wbs-3 --title "Update tests" --agent "@copilot" --seq 3
+wbs.js job run wbs-3
+```
+**Why WBS**: Context preservation critical, step-by-step validation needed
+### 4. Simple Code Fix (No WBS)
+**Scenario**: Fix a typo in documentation
+```bash
+# Direct delegation - immediate execution
+crewx x "@claude Fix typo in README.md line 42"
+```
+**Why Direct**: Single-step, < 15 minutes, no tracking needed
+## 30-Minute Timeboxing
+| Category | Time | Description |
+|----------|------|-------------|
+| Minimum | 15 min | Below this -> don't separate as Job |
+| Optimal | 25-30 min | Target duration |
+| Maximum | 45 min | Above this -> re-decompose |
+**Rationale**: LLM context limits (Lost in the Middle, Context Rot) + Pomodoro Technique
+## WARNING: Job Description Template (MANDATORY)
+**All Jobs must follow the template below.** Vague Job Descriptions are a leading cause of incomplete work.
+### Template
+```markdown
+**Deliverables:**
+1. path/to/file1.tsx - description
+2. path/to/file2.ts - description
+3. Modify existing file: path/to/existing.tsx
+**Done Criteria:**
+- [ ] Verify component rendering
+- [ ] Verify store integration works
+- [ ] Verify route addition and navigation
+**References:**
+- docs/ui-screens/screens/XX.md
+- Wireframe/design links
+```
+### Usage Example
+```bash
+# [BAD] BAD - Vague Job Description
+node wbs.js job add wbs-1 \
+  --title "Agent settings screen" \
+  --desc "Display crewx.yaml agent list. Model/provider/prompt editing UI." \
+  --agent "@launcher_gemini_dev"
+# [OK] GOOD - Clear deliverables and done criteria
+node wbs.js job add wbs-1 \
+  --title "Agent settings screen" \
+  --desc "**Deliverables:**
+1. src/renderer/components/AgentConfig/AgentConfigPage.tsx - Agent list page
+2. src/renderer/components/AgentConfig/AgentEditModal.tsx - Edit modal
+3. src/renderer/App.tsx - Add /agents route
+4. src/renderer/components/Layout/Sidebar.tsx - Add menu item
+**Done Criteria:**
+- [ ] Agent list displays when navigating to /agents
+- [ ] Edit modal opens on button click
+- [ ] Changes saved to crewx.yaml on save
+**References:** docs/ui-screens/screens/03-agent.md" \
+  --agent "@launcher_gemini_dev"
+```
+### Why Is This Mandatory?
+| Problem | Vague Job Description | With Template |
+|---------|----------------------|---------------|
+| **Scope interpretation** | Agent interprets arbitrarily | Clear file list |
+| **Completion judgment** | Manual "done" marking | Checklist verification |
+| **Preventing omissions** | Only Store without UI | All deliverables specified |
+| **Review ease** | Unclear what to verify | Checklist-based review |
+### Integration Test Job Template
+Integration test Jobs must specify verification items in detail:
+```bash
+node wbs.js job add wbs-1 \
+  --title "Integration test" \
+  --desc "**Verification Scenarios:**
+1. Onboarding -> Preset selection -> Installation complete
+2. Dashboard -> Agent list displays
+3. Agent settings -> Edit -> Save
+**Verification Methods:**
+- [ ] Manual execution of each scenario
+- [ ] Screenshot capture (using skills/playwright-python)
+- [ ] Error log inspection
+**Pass Criteria:**
+- All scenarios work correctly
+- No console errors" \
+  --agent "@launcher_codex_dev"
+```
+## Installation
+```bash
+cd skills/wbs
+npm install
+```
+Requires Node.js 16+.
+## Commands Reference
+### Project Management Commands
+| Command | Syntax | Description |
+|---------|--------|-------------|
+| **create** | `wbs.js create "Title" [--detail path]` | Create new WBS project with sequential ID (wbs-1, wbs-2, ...) |
+| **list** | `wbs.js list [--json]` | List all projects with status and progress |
+| **status** | `wbs.js status <wbs-id> [--json]` | Get detailed project info including all jobs and summary stats |
+| **delete** | `wbs.js delete <wbs-id>` | Delete project and all associated jobs/executions (irreversible) |
+### Job Management Commands
+| Command | Syntax | Description |
+|---------|--------|-------------|
+| **job add** | `wbs.js job add <wbs-id> --title "Title" --agent "@agent" [options]` | Add new job to project. Options: `--desc`, `--seq`, `--issue` |
+| **job list** | `wbs.js job list <wbs-id> [--json]` | List all jobs ordered by sequence number |
+| **job update** | `wbs.js job update <job-id\|slug> [options]` | Update job properties. Options: `--status`, `--title`, `--desc`, `--agent`, `--seq`, `--issue` |
+| **job run** | `wbs.js job run <wbs-id>` | Execute all pending jobs sequentially (30-min timeout each) |
+| **job next** | `wbs.js job next <wbs-id>` | Execute only the next pending job (manual step-by-step) |
+| **job retry** | `wbs.js job retry <job-id\|slug>` | Retry a failed or completed job |
+### Execution Management Commands
+| Command | Syntax | Description |
+|---------|--------|-------------|
+| **exec list** | `wbs.js exec list <job-id\|slug> [--json]` | List execution history for a job |
+| **exec status** | `wbs.js exec status <exec-id> [--json]` | Get detailed execution info |
+| **exec kill** | `wbs.js exec kill <exec-id>` | Kill a running execution |
+| **exec running** | `wbs.js exec running [--json]` | List all currently running executions |
+### Coordinator Commands (Natural Language)
+| Command | Syntax | Description |
+|---------|--------|-------------|
+| **q** | `wbs.js q "question"` | Ask coordinator a question (via `@wbs_coordinator`) |
+| **x** | `wbs.js x "request"` | Request coordinator to execute an action |
+### Daemon Commands (Background Scheduler)
+| Command | Syntax | Description |
+|---------|--------|-------------|
+| **daemon start** | `wbs.js daemon start` | Start background scheduler |
+| **daemon stop** | `wbs.js daemon stop` | Stop running daemon |
+| **daemon status** | `wbs.js daemon status` | Check daemon status |
+| **daemon tick** | `wbs.js daemon tick` | Manual tick for testing |
+### Common Usage Patterns
+```bash
+# Create and run a complete project
+wbs.js create "User Authentication"
+wbs.js job add wbs-1 --title "Design schema" --agent "@claude:sonnet" --seq 1
+wbs.js job add wbs-1 --title "Implement API" --agent "@copilot" --seq 2
+wbs.js job add wbs-1 --title "Write tests" --agent "@claude:sonnet" --seq 3
+wbs.js job run wbs-1
+# Check progress
+wbs.js status wbs-1
+# Handle failures (use job-id or slug)
+wbs.js job list wbs-1 --json | jq '.[] | select(.status=="failed")'
+wbs.js job retry wbs-1-3      # by slug
+wbs.js job retry job-5         # by job-id
+# Issue-based workflow
+wbs.js job add wbs-2 --title "Fix bug" --agent "@claude" --issue 42
+```
+### Output Formats
+- **Default**: Human-readable tables with emoji status icons
+- **--json**: Machine-parseable JSON for scripting and automation
+For detailed command documentation, see:
+- [COMMANDS.md](./COMMANDS.md) - Complete project commands reference
+- [job-management.md](./job-management.md) - Comprehensive job management guide
+## Practical Usage Examples
+This section provides comprehensive real-world examples of using the WBS skill effectively.
+### Example 1: Simple Workflow (Create -> Add Jobs -> Run)
+The most basic WBS workflow involves creating a project, adding jobs, and running them sequentially.
+**Scenario**: Build a simple REST API for a todo application
+```bash
+# 1. Create the project
+node wbs.js create "Todo REST API"
+```
+**Expected output:**
+```json
+{
+  "id": "wbs-1",
+  "title": "Todo REST API",
+  "status": "planning",
+  "detailPath": "skills/wbs/details/wbs-1-detail.md",
+  "created_at": "2025-12-18T08:00:00.000Z"
+}
+```
+```bash
+# 2. Add jobs for implementation
+node wbs.js job add wbs-1 \
+  --title "Design database schema" \
+  --agent "@claude:sonnet" \
+  --seq 1 \
+  --desc "Create SQLite schema for todos table with id, title, completed, created_at fields"
+node wbs.js job add wbs-1 \
+  --title "Implement CRUD endpoints" \
+  --agent "@copilot" \
+  --seq 2 \
+  --desc "Create Express routes: GET /todos, POST /todos, PUT /todos/:id, DELETE /todos/:id"
+node wbs.js job add wbs-1 \
+  --title "Add input validation" \
+  --agent "@claude:sonnet" \
+  --seq 3 \
+  --desc "Implement request validation middleware using express-validator"
+node wbs.js job add wbs-1 \
+  --title "Write integration tests" \
+  --agent "@copilot" \
+  --seq 4 \
+  --desc "Create test suite covering all CRUD operations using supertest"
+```
+```bash
+# 3. Review the planned jobs
+node wbs.js status wbs-1
+```
+**Expected output:**
+```
+[INFO] Todo REST API (wbs-1)
+   Status: planning | Progress: 0% (0/4)
+   Detail: skills/wbs/details/wbs-1-detail.md
+   Jobs:
+   | Status | #  | Slug      | ID    | Task                      | Agent           |
+   |--------|----|-----------|-------|--------------------------|-----------------|
+   | [ ]  | 1  | wbs-1-1   | job-1 | Design database schema    | @claude:sonnet  |
+   | [ ]  | 2  | wbs-1-2   | job-2 | Implement CRUD endpoints  | @copilot        |
+   | [ ]  | 3  | wbs-1-3   | job-3 | Add input validation      | @claude:sonnet  |
+   | [ ]  | 4  | wbs-1-4   | job-4 | Write integration tests   | @copilot        |
+```
+```bash
+# 4. Run all jobs
+node wbs.js job run wbs-1
+```
+**Expected output:**
+```
+==================================================
+[WBS] Starting project: Todo REST API
+==================================================
+[WBS] Running job: Design database schema
+[WBS] Agent: @claude:sonnet
+[WBS] Description: Create SQLite schema for todos table...
+[WBS] Timeout: 30 minutes
+--------------------------------------------------
+[Agent executes and produces output...]
+--------------------------------------------------
+[WBS] Job completed: Design database schema
+[WBS] Running job: Implement CRUD endpoints
+[WBS] Agent: @copilot
+[WBS] Timeout: 30 minutes
+--------------------------------------------------
+[Agent executes and produces output...]
+--------------------------------------------------
+[WBS] Job completed: Implement CRUD endpoints
+[... continues for remaining jobs ...]
+==================================================
+[WBS] Project completed: Todo REST API
+[WBS] Completed: 4, Failed: 0
+==================================================
+```
+```bash
+# 5. Verify completion
+node wbs.js status wbs-1
+```
+**Final output:**
+```
+[INFO] Todo REST API (wbs-1)
+   Status: completed | Progress: 100% (4/4)
+   Detail: skills/wbs/details/wbs-1-detail.md
+   Jobs:
+   | Status | #  | Slug      | ID    | Task                      | Agent           | Status    |
+   |--------|----|-----------|-------|--------------------------|-----------------|-----------|
+   | [OK]   | 1  | wbs-1-1   | job-1 | Design database schema    | @claude:sonnet  | completed |
+   | [OK]   | 2  | wbs-1-2   | job-2 | Implement CRUD endpoints  | @copilot        | completed |
+   | [OK]   | 3  | wbs-1-3   | job-3 | Add input validation      | @claude:sonnet  | completed |
+   | [OK]   | 4  | wbs-1-4   | job-4 | Write integration tests   | @copilot        | completed |
+```
+---
+### Example 2: Issue-Based Workflow
+Use WBS to manage multiple GitHub issues systematically.
+**Scenario**: Fix authentication-related bugs tracked in GitHub
+```bash
+# 1. Create project for bug fixes
+node wbs.js create "Authentication Bug Fixes"
+```
+**Output:**
+```json
+{
+  "id": "wbs-2",
+  "title": "Authentication Bug Fixes",
+  "status": "planning"
+}
+```
+```bash
+# 2. Add jobs linked to GitHub issues
+node wbs.js job add wbs-2 \
+  --title "Fix: Login fails with special characters in password" \
+  --agent "@claude:sonnet" \
+  --issue 123 \
+  --seq 1
+node wbs.js job add wbs-2 \
+  --title "Fix: Session timeout not working" \
+  --agent "@claude:sonnet" \
+  --issue 124 \
+  --seq 2
+node wbs.js job add wbs-2 \
+  --title "Fix: Password reset email not sent" \
+  --agent "@claude:sonnet" \
+  --issue 125 \
+  --seq 3
+```
+**What happens during execution:**
+When you run `node wbs.js job run wbs-2`, each job receives these instructions:
+```
+## Task Instructions
+Process GitHub Issue #123.
+**Follow your existing development process:**
+1. Check the issue with `gh issue view 123`
+2. Create branch and work
+3. Create PR
+4. Comment results on the issue
+WBS Tracking Info:
+- WBS: wbs-2
+- Job: job-1
+```
+**Advantages:**
+- Automatic issue-branch-PR linking
+- Agent follows its own development workflow
+- Easy progress tracking via GitHub
+- Issue comments document resolution
+---
+### Example 3: Step-by-Step Execution
+Execute jobs manually one at a time with review between each step.
+**Scenario**: Refactoring legacy code where each step needs verification
+```bash
+# 1. Create project
+node wbs.js create "Legacy Code Refactoring"
+# 2. Add jobs
+node wbs.js job add wbs-3 \
+  --title "Extract UserService from monolithic controller" \
+  --agent "@claude:opus" \
+  --seq 1 \
+  --desc "Move user-related logic from AppController to new UserService class"
+node wbs.js job add wbs-3 \
+  --title "Add dependency injection" \
+  --agent "@claude:sonnet" \
+  --seq 2 \
+  --desc "Refactor UserService to use constructor injection for database"
+node wbs.js job add wbs-3 \
+  --title "Update unit tests" \
+  --agent "@copilot" \
+  --seq 3 \
+  --desc "Modify tests to work with new UserService architecture"
+node wbs.js job add wbs-3 \
+  --title "Verify integration tests pass" \
+  --agent "@copilot" \
+  --seq 4 \
+  --desc "Run full test suite and fix any integration issues"
+```
+```bash
+# 3. Execute first job only
+node wbs.js job next wbs-3
+```
+**Output:**
+```
+[WBS] Running job: Extract UserService from monolithic controller
+[WBS] Agent: @claude:opus
+[WBS] Timeout: 30 minutes
+--------------------------------------------------
+[Agent output...]
+--------------------------------------------------
+[WBS] Job completed: Extract UserService from monolithic controller
+{
+  "success": true,
+  "execId": "exec-1"
+}
+```
+```bash
+# 4. Review changes before continuing
+git diff
+npm test
+# 5. If satisfied, run next job
+node wbs.js job next wbs-3
+```
+**Output:**
+```
+[WBS] Running job: Add dependency injection
+[WBS] Agent: @claude:sonnet
+...
+```
+```bash
+# 6. Continue step by step
+node wbs.js status wbs-3  # Check progress
+node wbs.js job next wbs-3  # Run next job
+```
+**Use cases for step-by-step execution:**
+- Code reviews between steps
+- Testing after each change
+- Learning/understanding the codebase
+- High-risk refactoring
+- Debugging job configurations
+---
+### Example 4: Handling Failures
+Recover from failed jobs and retry with updated configurations.
+**Scenario**: API implementation where initial attempts fail
+```bash
+# 1. Create project and add jobs
+node wbs.js create "Payment API Integration"
+node wbs.js job add wbs-4 \
+  --title "Integrate Stripe SDK" \
+  --agent "@copilot" \
+  --seq 1
+node wbs.js job add wbs-4 \
+  --title "Implement payment endpoint" \
+  --agent "@claude:sonnet" \
+  --seq 2
+node wbs.js job add wbs-4 \
+  --title "Add webhook handler" \
+  --agent "@claude:sonnet" \
+  --seq 3
+# 2. Run all jobs
+node wbs.js job run wbs-4
+```
+**Suppose job-2 fails:**
+```
+[WBS] Running job: Implement payment endpoint
+[WBS] Agent: @claude:sonnet
+--------------------------------------------------
+Error: Missing API key configuration
+--------------------------------------------------
+[WBS] Job failed: Implement payment endpoint
+```
+```bash
+# 3. Check which jobs failed
+node wbs.js job list wbs-4 --json | jq '.[] | select(.status=="failed")'
+```
+**Output:**
+```json
+{
+  "id": "job-2",
+  "wbs_id": "wbs-4",
+  "title": "Implement payment endpoint",
+  "status": "failed",
+  "agent": "@claude:sonnet",
+  "seq": 2
+}
+```
+```bash
+# 4. Review execution history
+node wbs.js exec list job-2
+```
+**Output:**
+```
+[INFO] Executions for job-2
+| Status | ID      | PID   | Start               | End                 | Code |
+|--------|---------|-------|---------------------|---------------------|------|
+| [BAD]   | exec-2  | 45678 | 2025-12-18 09:15:00 | 2025-12-18 09:18:00 | 1    |
+```
+```bash
+# 5. Fix the issue (add environment variable or update job description)
+node wbs.js job update job-2 \
+  --desc "Implement payment endpoint. Use STRIPE_API_KEY from .env file. Handle both test and production modes."
+# 6. Retry the failed job
+node wbs.js job retry job-2
+```
+**Output:**
+```
+[WBS] Retrying job: Implement payment endpoint
+[WBS] Running job: Implement payment endpoint
+[WBS] Agent: @claude:sonnet
+[WBS] Timeout: 30 minutes
+--------------------------------------------------
+[Agent output...]
+--------------------------------------------------
+[WBS] Job completed: Implement payment endpoint
+{
+  "success": true,
+  "execId": "exec-5"
+}
+```
+```bash
+# 7. Continue with remaining jobs
+node wbs.js job run wbs-4
+```
+**Final status:**
+```
+[INFO] Payment API Integration (wbs-4)
+   Status: completed | Progress: 100% (3/3)
+   Jobs:
+   | Status | #  | ID    | Task                      | Status    |
+   |--------|----|----|--------------------------|-----------|
+   | [OK]   | 1  | job-1 | Integrate Stripe SDK      | completed |
+   | [OK]   | 2  | job-2 | Implement payment endpoint| completed |
+   | [OK]   | 3  | job-3 | Add webhook handler       | completed |
+```
+**Batch retry all failed jobs:**
+```bash
+# Find and retry all failed jobs in a project
+for job in $(node wbs.js job list wbs-4 --json | jq -r '.[] | select(.status=="failed") | .id'); do
+  echo "Retrying $job..."
+  node wbs.js job retry $job
+done
+```
+---
+### Example 5: Complex Multi-Agent Coordination
+Distribute work across different AI agents based on their strengths.
+**Scenario**: Build a full-stack feature with frontend, backend, and tests
+```bash
+# 1. Create project
+node wbs.js create "User Profile Feature"
+# 2. Add jobs with appropriate agent selection
+# Backend work - @claude:sonnet for complex logic
+node wbs.js job add wbs-5 \
+  --title "Design User Profile data model" \
+  --agent "@claude:sonnet" \
+  --seq 1 \
+  --desc "Create schema with fields: avatar, bio, social_links, preferences"
+# Implementation - @copilot for straightforward coding
+node wbs.js job add wbs-5 \
+  --title "Implement profile CRUD API" \
+  --agent "@copilot" \
+  --seq 2 \
+  --desc "REST endpoints for profile operations with validation"
+# Complex architecture - @claude:opus for advanced decisions
+node wbs.js job add wbs-5 \
+  --title "Design avatar upload system" \
+  --agent "@claude:opus" \
+  --seq 3 \
+  --desc "S3 integration with image processing, CDN, and caching strategy"
+# Implementation again
+node wbs.js job add wbs-5 \
+  --title "Implement avatar upload" \
+  --agent "@copilot" \
+  --seq 4 \
+  --desc "File upload endpoint with S3 SDK and image optimization"
+# Frontend - @claude:sonnet for React components
+node wbs.js job add wbs-5 \
+  --title "Create profile edit form" \
+  --agent "@claude:sonnet" \
+  --seq 5 \
+  --desc "React component with form validation and avatar preview"
+# Testing - @copilot excels at test generation
+node wbs.js job add wbs-5 \
+  --title "Write comprehensive tests" \
+  --agent "@copilot" \
+  --seq 6 \
+  --desc "Unit tests for API, integration tests, and React Testing Library tests"
+# 3. Run the entire pipeline
+node wbs.js job run wbs-5
+```
+**Agent selection rationale:**
+- `@claude:sonnet`: Complex logic, architecture, React components
+- `@claude:opus`: Very complex architectural decisions
+- `@copilot`: Straightforward implementation, test generation
+- `@gemini`: Performance optimization, data analysis (not shown here)
+---
+### Example 6: Working with Detail Documents
+Use detail documents to provide comprehensive context to all jobs.
+```bash
+# 1. Create project with detail document
+node wbs.js create "E-commerce Checkout Flow" --detail ./docs/checkout-spec.md
+# The system creates: skills/wbs/details/wbs-6-detail.md
+```
+**Edit the detail document:**
+```bash
+# Edit skills/wbs/details/wbs-6-detail.md
+```
+**Content:**
+```markdown
+# E-commerce Checkout Flow
+## Overview
+Implement a secure checkout process for our e-commerce platform.
+## Requirements
+### Functional Requirements
+1. Multi-step checkout (cart -> shipping -> payment -> confirmation)
+2. Address validation with autocomplete
+3. Multiple payment methods (credit card, PayPal)
+4. Order summary with promo codes
+5. Email confirmation
+### Technical Requirements
+- Payment processing via Stripe
+- Address validation via Google Maps API
+- Session management for cart persistence
+- Transactional email via SendGrid
+### Security
+- PCI compliance for credit card handling
+- HTTPS only
+- CSRF protection
+- Rate limiting on payment endpoints
+### Performance
+- Checkout flow should complete in < 3 seconds
+- Optimize for mobile devices
+## References
+- [Stripe API Docs](https://stripe.com/docs/api)
+- [Design Mockups](./figma-link)
+```
+**Add jobs:**
+```bash
+node wbs.js job add wbs-6 \
+  --title "Implement multi-step form navigation" \
+  --agent "@claude:sonnet" \
+  --seq 1
+node wbs.js job add wbs-6 \
+  --title "Integrate Stripe payment" \
+  --agent "@copilot" \
+  --seq 2
+# ... more jobs
+```
+**When jobs run, they automatically receive the detail document content as context.**
+---
+### Example 7: Monitoring and JSON Output
+Automate WBS monitoring and integrate with other tools.
+**Check project status programmatically:**
+```bash
+# Get JSON output for scripting
+node wbs.js status wbs-1 --json | jq '.summary'
+```
+**Output:**
+```json
+{
+  "total_jobs": 4,
+  "completed": 4,
+  "failed": 0,
+  "pending": 0,
+  "running": 0,
+  "progress": 100
+}
+```
+**Create a monitoring script:**
+```bash
+#!/bin/bash
+# monitor-wbs.sh
+WBS_ID="wbs-7"
+while true; do
+  clear
+  echo "======================================="
+  echo "  WBS Monitor - $WBS_ID"
+  echo "======================================="
+  node wbs.js status $WBS_ID
+  PROGRESS=$(node wbs.js status $WBS_ID --json | jq -r '.summary.progress')
+  if [ "$PROGRESS" -eq 100 ]; then
+    echo ""
+    echo "[OK] Project complete!"
+    break
+  fi
+  echo ""
+  echo "[WAIT] Checking again in 60 seconds..."
+  sleep 60
+done
+```
+**Run monitor:**
+```bash
+chmod +x monitor-wbs.sh
+./monitor-wbs.sh
+```
+**Export jobs to CSV:**
+```bash
+# Export job list
+echo "ID,Title,Status,Agent,Seq" > jobs-export.csv
+node wbs.js job list wbs-1 --json | \
+  jq -r '.[] | [.id,.title,.status,.agent,.seq] | @csv' >> jobs-export.csv
+```
+**Check specific job execution history:**
+```bash
+# List all executions for a job
+node wbs.js exec list job-5 --json | jq '.'
+```
+---
+### Example 8: Recovering from Interruptions
+Handle scenarios where execution is interrupted.
+**Scenario**: Long-running project interrupted by system crash
+```bash
+# 1. Check current status
+node wbs.js list
+```
+**Output:**
+```
+[INFO] WBS Projects (3)
+| ID    | Title                   | Status    | Progress  |
+|-------|-----------------------|----------|----------|
+| wbs-1 | Todo REST API         | completed| 100% 4/4 |
+| wbs-2 | Bug Fixes             | running  | 50% 2/4  |
+| wbs-3 | Refactoring           | planning | 0% 0/5   |
+```
+```bash
+# 2. Check which jobs were running
+node wbs.js status wbs-2
+```
+**Output:**
+```
+[INFO] Bug Fixes (wbs-2)
+   Status: running | Progress: 50% (2/4)
+   Jobs:
+   | Status | #  | ID    | Task           | Status    |
+   |--------|----|----|---------------|-----------|
+   | [OK]   | 1  | job-1 | Fix bug #123   | completed |
+   | [OK]   | 2  | job-2 | Fix bug #124   | completed |
+   | [~]   | 3  | job-3 | Fix bug #125   | running   |
+   | [ ]  | 4  | job-4 | Fix bug #126   | pending   |
+```
+```bash
+# 3. Check if the running job actually completed
+node wbs.js exec list job-3
+```
+**If the execution failed or timed out:**
+```
+| Status | ID      | PID   | Start               | End                 | Code |
+|--------|---------|-------|---------------------|---------------------|------|
+| [BAD]   | exec-7  | 23456 | 2025-12-18 10:30:00 | N/A (timeout)       | -1   |
+```
+```bash
+# 4. Reset the job and retry
+node wbs.js job update job-3 --status pending
+node wbs.js job retry job-3
+# 5. Continue with remaining jobs
+node wbs.js job run wbs-2
+```
+---
+### Summary: Quick Command Reference
+**Basic workflow:**
+```bash
+# Create -> Add -> Run -> Check
+node wbs.js create "Project Name"
+node wbs.js job add wbs-X --title "Task" --agent "@agent" --seq N
+node wbs.js job run wbs-X
+node wbs.js status wbs-X
+```
+**Issue-based workflow:**
+```bash
+node wbs.js create "Bug Fixes"
+node wbs.js job add wbs-X --title "Fix bug" --agent "@agent" --issue 123
+node wbs.js job run wbs-X
+```
+**Step-by-step workflow:**
+```bash
+node wbs.js job next wbs-X  # Run one job
+# Review changes...
+node wbs.js job next wbs-X  # Run next
+```
+**Handle failures (job-id or slug):**
+```bash
+node wbs.js job list wbs-X --json | jq '.[] | select(.status=="failed")'
+node wbs.js job update wbs-X-Y --desc "Updated instructions"  # by slug
+node wbs.js job retry wbs-X-Y                                  # by slug
+node wbs.js job retry job-Y                                    # by job-id
+```
+**Monitoring:**
+```bash
+node wbs.js list
+node wbs.js status wbs-X
+node wbs.js status wbs-X --json | jq '.summary'
+```
+For more examples, see:
+- [EXAMPLE.md](./EXAMPLE.md) - Korean language detailed walkthrough
+- [job-management.md](./job-management.md) - Job-specific examples and patterns
+## Usage in Coordinator Agent
+The coordinator agent uses this skill programmatically:
+```javascript
+const wbs = require('./wbs.js');
+// 1. Create project
+const id = wbs.create('User Authentication Implementation');
+// 2. Add jobs (AI decomposed)
+wbs.addJob(id, { title: 'Design User model', agent: '@claude:sonnet', seq: 1 });
+wbs.addJob(id, { title: 'Implement login API', agent: '@copilot', seq: 2 });
+wbs.addJob(id, { title: 'Write tests', agent: '@claude:sonnet', seq: 3 });
+// 3. Execute
+await wbs.run(id);
+// 4. Check status
+console.log(wbs.status(id));
+```
+## Job Status Flow
+```
+pending -> running -> completed
+                  -> failed
+```
+## Key Design Decisions
+1. **AI makes intelligent decisions** - Complexity analysis, job decomposition
+2. **Code handles state only** - wbs.js does DB CRUD + worker execution
+3. **30-minute timeboxing** - Each job is 15-45 minutes
+4. **Start simple, improve iteratively** - MVP first
+## API Reference
+### Project Management
+#### `wbs.create(title, options?)`
+Create a new WBS project. Returns project ID.
+- `options.detailPath`: Path to detail document (auto-created if not specified)
+#### `wbs.list()`
+List all WBS projects.
+#### `wbs.status(wbsId)`
+Get project and all jobs status.
+#### `wbs.delete(wbsId)`
+Delete a project and all associated jobs/executions.
+### Job Management
+#### `wbs.addJob(wbsId, { title, description?, agent, seq?, issue_number? })`
+Add a job to the project. Returns job ID.
+- `title`: Job title (short name)
+- `description`: Detailed instructions for the agent
+- `agent`: Worker agent mention (e.g., `@crewx_claude_dev`)
+- `seq`: Execution order (default: 0)
+- `issue_number`: Related GitHub issue number
+#### `wbs.getNextJob(wbsId)`
+Get the next pending job. Returns job object or null.
+#### `wbs.updateJob(jobId, status)`
+Update job status. Status: `pending`, `running`, `completed`, `failed`.
+#### `wbs.runWorker(job)`
+Execute a single worker. Returns `{ success, error?, execId }`.
+#### `wbs.run(wbsId)`
+Execute all pending jobs sequentially.
+### Execution Management
+#### `wbs.createExecution(jobId, pid)`
+Create a new execution record. Returns execution ID.
+#### `wbs.updateExecution(execId, status, options?)`
+Update execution status.
+- `options.exitCode`: Process exit code
+- `options.error`: Error message
+#### `wbs.getExecution(execId)`
+Get execution by ID.
+#### `wbs.listExecutions(jobId)`
+List all executions for a job.
+#### `wbs.killExecution(execId)`
+Kill a running execution. Returns boolean success.
+#### `wbs.getRunningExecutions()`
+Get all currently running executions.
+## Related Documentation
+- [WBS Skill Spec](/docs/cto/designs/wbs-skill-spec.md)
+- [CrewX CLI Documentation](/packages/cli/AGENTS.md)