specweave 0.10.0 → 0.11.0

package/plugins/specweave-ado/skills/ado-sync/SKILL.md

@@ -1,16 +1,20 @@
 ---
 name: ado-sync
-description: Bidirectional synchronization between SpecWeave increments and Azure DevOps work items. Creates work items from increments, tracks progress via comments, updates increment status from work item state, and closes work items when increments complete. Activates for: Azure DevOps, ADO, work items, project management, sync to ADO, ADO integration, TFS integration.
+description: Bidirectional synchronization between SpecWeave increments and Azure DevOps work items (two-way sync by default). Creates work items from increments, tracks progress via comments, updates increment status from work item state, syncs changes in both directions automatically. Activates for: Azure DevOps, ADO, work items, project management, sync to ADO, ADO integration, TFS integration, bidirectional ADO sync.
 ---
 
 # Azure DevOps Sync Skill
 
 **Purpose**: Seamlessly sync SpecWeave increments with Azure DevOps work items for unified project tracking.
 
+**Default Behavior**: **Bidirectional (two-way) sync** - Changes in either system are automatically synchronized
+
 **Capabilities**:
+- Bidirectional sync: SpecWeave ↔ ADO (default)
 - Create ADO work items from increments
-- Sync task progress → ADO comments  
-- Update increment status from ADO state
+- Sync task progress → ADO comments
+- Update increment status ← ADO state changes
+- Pull ADO comments and field updates → SpecWeave
 - Close work items when increments complete
 - Support for Epics, Features, User Stories
 

package/plugins/specweave-github/agents/github-manager/AGENT.md

@@ -6,23 +6,33 @@
 
 **Tools**: Read, Write, Edit, Bash (GitHub CLI)
 
+**Default Behavior**: **Bidirectional sync** (two-way) - Synchronizes changes in both directions automatically
+
 ---
 
 ## Capabilities
 
 As the GitHub Manager agent, I specialize in:
 
-### 1. Issue Management
+### 1. Bidirectional Synchronization (Default)
+- **Two-Way Sync**: Keep SpecWeave and GitHub synchronized automatically
+  - **FROM GitHub**: Pull status changes, labels, comments, state updates
+  - **TO GitHub**: Push task completion, progress updates, metadata
+- **Conflict Resolution**: Detect and resolve conflicts between systems
+- **Smart Merging**: Merge changes from both directions intelligently
+- **Change Detection**: Track what changed in both systems since last sync
+
+### 2. Issue Management
 - **Create Issues**: Generate well-formatted GitHub issues from increment specs
-- **Update Issues**: Sync progress, add comments, update labels
+- **Update Issues**: Sync progress, add comments, update labels (bidirectional)
 - **Close Issues**: Close issues with completion summaries
 - **Link Issues**: Connect related issues, PRs, and increments
 - **Bulk Operations**: Batch create/update/close issues
 
-### 2. Progress Tracking
+### 3. Progress Tracking
 - **Task Checklists**: Generate and update task checklists in issues
 - **Progress Comments**: Post detailed task completion comments
-- **Status Updates**: Real-time sync of increment status to GitHub
+- **Status Updates**: Bidirectional sync of increment status ↔ GitHub issue state
 - **Time Tracking**: Track estimated vs actual time per task
 - **Milestone Progress**: Update milestone completion percentages
 

package/plugins/specweave-github/commands/specweave-github-sync.md

@@ -26,32 +26,64 @@ Synchronize the current state of a SpecWeave increment with its GitHub issue acr
 - `--comment`: Post progress comment (default)
 - `--labels`: Update issue labels based on status
 - `--force`: Force sync even if up-to-date
-- `--direction`: Sync direction (`to-github`, `from-github`, `bidirectional`)
+- `--direction`: Sync direction (`to-github`, `from-github`, `bidirectional` - **default: bidirectional**)
 - `--all`: Sync all active increments
 
 ### Safety Options
 - `--dry-run`: Preview changes without applying
 - `--skip-rate-check`: Skip rate limit validation (not recommended)
 
+## Sync Direction
+
+**Default: Bidirectional** (two-way sync)
+
+SpecWeave syncs changes in **both directions** by default:
+
+| Direction | What It Does | Use When |
+|-----------|-------------|----------|
+| **`bidirectional`** (default) | SpecWeave ↔ GitHub<br>• Pull changes FROM GitHub (status, labels, comments)<br>• Push changes TO GitHub (tasks, progress, metadata) | **Always** (recommended for keeping both systems in sync) |
+| `to-github` | SpecWeave → GitHub only<br>• Push increment progress to GitHub<br>• Don't pull GitHub changes back | Read-only GitHub usage, or when GitHub is downstream |
+| `from-github` | GitHub → SpecWeave only<br>• Pull GitHub issue updates<br>• Don't push SpecWeave changes | Importing GitHub issues, or when SpecWeave is downstream |
+
+**Why Bidirectional?**
+- ✅ Keep both systems synchronized automatically
+- ✅ GitHub status changes update SpecWeave (closed issue → completed increment)
+- ✅ SpecWeave task completion updates GitHub (task done → checklist updated)
+- ✅ Team members can work in either tool
+- ✅ No data loss from changes in either system
+
+**Override if needed:**
+```bash
+# Push only (one-way to GitHub)
+/specweave-github:sync 0004 --direction to-github
+
+# Pull only (one-way from GitHub)
+/specweave-github:sync 0004 --direction from-github
+```
+
 ## Examples
 
 ```bash
-# Interactive sync (select profile + time range)
+# Interactive bidirectional sync (default - two-way)
 /specweave-github:sync 0004
 
-# Use specific profile
+# Use specific profile (still bidirectional by default)
 /specweave-github:sync 0004 --profile specweave-dev
 
-# Specify time range
+# Specify time range (bidirectional)
 /specweave-github:sync 0004 --time-range 1M
 
-# Full sync with all options
+# Full bidirectional sync with all options
 /specweave-github:sync 0004 --profile main --time-range 1M --tasks --labels
 
+# One-way sync examples (override default)
+/specweave-github:sync 0004 --direction to-github     # Push only
+/specweave-github:sync 0004 --direction from-github   # Pull only
+
 # Dry run to preview changes
 /specweave-github:sync 0004 --dry-run
 
-# Force sync all increments
+# Force sync all increments (bidirectional)
 /specweave-github:sync --all --force
 ```
 
@@ -151,35 +183,52 @@ Continue with sync? [Y/n]:
 If confirmed, sync proceeds with progress updates:
 
 ```
-🔄 Syncing increment 0004 to GitHub...
+🔄 Bidirectional sync for increment 0004...
 
 ✓ Profile loaded: specweave-dev
 ✓ GitHub repository: anton-abyzov/specweave
 ✓ Rate limit check: PASSED (4,850/5,000 remaining)
+✓ Sync direction: bidirectional (two-way)
 
 Fetching increment state...
 ✓ Increment loaded: 0004-plugin-architecture
 ✓ GitHub issue: #130
 ✓ Last synced: 30 minutes ago
 
-Detecting changes...
+Detecting changes (both directions)...
+
+FROM GitHub:
+✓ Issue status changed: open → closed
+✓ Label added: ready-for-release
+✓ 2 new comments from team
+
+FROM SpecWeave:
 ✓ 3 new tasks completed (T-005, T-006, T-007)
 ✓ Progress: 4/48 → 7/48 (15%)
 ✓ Current task: T-008
 
-Syncing to GitHub...
+Syncing TO GitHub...
 ✓ Posted progress comment (ID: 1234567)
 ✓ Updated task checklist (7 tasks marked complete)
 ✓ Updated labels: +in-progress
 ✓ Metadata updated
 
+Syncing FROM GitHub...
+✓ Updated increment status: active → completed
+✓ Applied label: ready-for-release
+✓ Imported 2 team comments to increment notes
+
 Rate limit after sync: 4,570/5,000 (91% available)
 
-✅ Sync Complete!
+✅ Bidirectional Sync Complete!
+
+   SpecWeave ↔ GitHub synchronized
+   • Pushed: 3 task updates, progress comment
+   • Pulled: Status change, label, 2 comments
 
 GitHub Issue: https://github.com/anton-abyzov/specweave/issues/130
 Last synced: just now
-Next sync: Use /specweave-github:sync 0004 when ready
+Next sync: Automatic (hook-based) or manual when ready
 ```
 
 ## Key Features

package/plugins/specweave-github/skills/github-sync/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: github-sync
-description: Bidirectional synchronization between SpecWeave increments and GitHub Issues. Creates issues from increments, tracks progress via comments, updates increment status from issue state, and closes issues when increments complete. Activates for GitHub sync, issue creation, increment tracking, GitHub integration, issue management, sync to GitHub.
+description: Bidirectional synchronization between SpecWeave increments and GitHub Issues (two-way sync by default). Creates issues from increments, tracks progress via comments, updates increment status from issue state, syncs changes in both directions automatically. Activates for GitHub sync, issue creation, increment tracking, GitHub integration, issue management, sync to GitHub, bidirectional sync.
 ---
 
 # GitHub Sync - Bidirectional Increment ↔ Issue Synchronization
 
 **Purpose**: Seamlessly synchronize SpecWeave increments with GitHub Issues for team visibility and project management.
 
+**Default Behavior**: **Bidirectional (two-way) sync** - Changes in either system are automatically synchronized
+
 **When to Use**:
 - Creating new increments (auto-create GitHub issue)
 - Syncing increment progress to GitHub (comments with task completion %)

package/plugins/specweave-jira/agents/jira-manager/AGENT.md

@@ -6,31 +6,41 @@
 
 **Tools**: Read, Write, Edit, Bash (curl for Jira API)
 
+**Default Behavior**: **Bidirectional sync** (two-way) - Synchronizes changes in both directions automatically
+
 ---
 
 ## Capabilities
 
 As the Jira Manager agent, I specialize in:
 
-### 1. Epic Management
+### 1. Bidirectional Synchronization (Default)
+- **Two-Way Sync**: Keep SpecWeave and Jira synchronized automatically
+  - **FROM Jira**: Pull status changes, priority updates, sprint assignments, comments
+  - **TO Jira**: Push task completion, progress updates, story points, metadata
+- **Conflict Resolution**: Detect and resolve conflicts between systems
+- **Smart Merging**: Merge changes from both directions intelligently
+- **Change Detection**: Track what changed in both systems since last sync
+
+### 2. Epic Management
 - **Create Epics**: Generate Jira Epics from SpecWeave increments
-- **Update Epics**: Sync progress, update status, add comments
+- **Update Epics**: Bidirectional sync of progress, status, comments
 - **Close Epics**: Close epics with completion summaries
 - **Link Epics**: Connect related epics, stories, and tasks
 - **Custom Fields**: Handle custom fields, labels, versions
 
-### 2. Story & Task Management
+### 3. Story & Task Management
 - **Create Stories**: Map SpecWeave specs to Jira Stories (PRD or RFC)
 - **Create Tasks**: Map SpecWeave tasks to Jira Tasks
-- **Update Status**: Real-time sync of task completion
+- **Update Status**: Bidirectional sync of task completion
 - **Subtasks**: Handle Jira subtasks and dependencies
 - **Bulk Operations**: Batch create/update stories and tasks
 
-### 3. Progress Tracking
-- **Sprint Progress**: Track epic progress within sprints
+### 4. Progress Tracking
+- **Sprint Progress**: Track epic progress within sprints (bidirectional)
 - **Story Points**: Calculate and update story points
-- **Status Updates**: Sync status changes bidirectionally
-- **Comments**: Post task completion comments
+- **Status Updates**: Bidirectional sync of status changes
+- **Comments**: Post task completion comments and import Jira comments
 - **Time Tracking**: Track estimated vs actual time
 
 ### 4. Jira API Operations

package/plugins/specweave-jira/commands/specweave-jira-sync.md

@@ -11,39 +11,60 @@ You are a Jira synchronization expert. Help the user sync between Jira and SpecW
 
 ### Epic-Level Operations
 
-**1. Import Jira Epic as SpecWeave Increment**
+**1. Bidirectional Sync (Default - Recommended)**
 ```
-/specweave:sync-jira import SCRUM-123
+/specweave-jira:sync 0003                    # Two-way sync (default)
+/specweave-jira:sync 0003 --direction bidirectional  # Explicit
 ```
 
-**2. Sync existing linked Increment with Jira**
+**2. Import Jira Epic as SpecWeave Increment**
 ```
-/specweave:sync-jira sync 0003
+/specweave-jira:sync import SCRUM-123        # One-time pull
+/specweave-jira:sync SCRUM-123 --direction from-jira  # Same as import
 ```
 
 **3. Export SpecWeave Increment to Jira**
 ```
-/specweave:sync-jira export 0001
+/specweave-jira:sync export 0001             # One-time push
+/specweave-jira:sync 0001 --direction to-jira  # Same as export
 ```
 
+### Sync Direction Options
+
+**Default: `bidirectional`** (two-way sync - recommended)
+
+- `--direction bidirectional`: SpecWeave ↔ Jira (default)
+  - Pull changes FROM Jira (status, priority, comments)
+  - Push changes TO Jira (tasks, progress, metadata)
+
+- `--direction to-jira`: SpecWeave → Jira only
+  - Push increment progress to Jira
+  - Don't pull Jira changes back
+  - Same as `export` operation
+
+- `--direction from-jira`: Jira → SpecWeave only
+  - Pull Jira issue updates
+  - Don't push SpecWeave changes
+  - Same as `import` operation
+
 ### Granular Item Operations
 
 **4. Add specific Story/Bug/Task to existing Increment**
 ```
-/specweave:sync-jira add SCRUM-1 to 0003
-/specweave:sync-jira add SCRUM-1              # Adds to current increment
+/specweave-jira:sync add SCRUM-1 to 0003
+/specweave-jira:sync add SCRUM-1              # Adds to current increment
 ```
 
 **5. Create Increment from specific items (cherry-pick)**
 ```
-/specweave:sync-jira create "User Authentication" from SCRUM-1 SCRUM-5 SCRUM-7
-/specweave:sync-jira create "Bug Fixes Sprint 1" from SCRUM-10 SCRUM-15 SCRUM-20
+/specweave-jira:sync create "User Authentication" from SCRUM-1 SCRUM-5 SCRUM-7
+/specweave-jira:sync create "Bug Fixes Sprint 1" from SCRUM-10 SCRUM-15 SCRUM-20
 ```
 
 **6. Show sync status**
 ```
-/specweave:sync-jira status
-/specweave:sync-jira status 0003              # Status of specific increment
+/specweave-jira:sync status
+/specweave-jira:sync status 0003              # Status of specific increment
 ```
 
 ## Your Task
@@ -154,19 +175,39 @@ When the user runs this command:
   | Task  | SCRUM-7  | Setup provider  |
   ```
 
-### Example 5: Sync Existing Increment
-**User**: `/specweave:sync-jira sync 0003`
+### Example 5: Bidirectional Sync (Default)
+**User**: `/specweave-jira:sync 0003`
 **You**:
 - Read increment 0003
 - Find linked Jira items (from spec.md frontmatter.work_items)
 - Fetch current state from Jira
-- Detect changes (status, priority, description)
-- Show conflicts if any
-- Apply sync bidirectionally
-- Display: "✅ Synced 0003 | Updated: 2 items | SCRUM-1 → in-progress, SCRUM-10 → completed"
+
+**Detect changes (both directions)**:
+- FROM Jira: Status changes, priority updates, comments
+- FROM SpecWeave: Task completion, progress updates
+
+**Show bidirectional sync summary**:
+```
+✅ Bidirectional Sync Complete: 0003 ↔ Jira
+
+FROM Jira:
+  • SCRUM-1: Status changed to In Progress
+  • SCRUM-10: Priority raised to P1
+
+FROM SpecWeave:
+  • 3 tasks completed (T-005, T-006, T-007)
+  • Progress: 60% → 75%
+
+Conflicts: None
+```
+
+**Handle conflicts if any**:
+- Show both versions (Jira vs SpecWeave)
+- Ask user which to keep or how to merge
+- Apply resolution bidirectionally
 
 ### Example 6: Status Overview
-**User**: `/specweave:sync-jira status`
+**User**: `/specweave-jira:sync status`
 **You**:
 - Scan all increments for Jira metadata
 - Show table:
@@ -188,10 +229,12 @@ When the user runs this command:
 
 ## Related Commands
 
-- `/specweave:sync-github` - Sync to GitHub issues
+- `/specweave-github:sync` - Sync to GitHub issues (also bidirectional by default)
 - `/specweave:increment` - Create new increment
 - `/specweave:validate` - Validate increment quality
 
 ---
 
+**Bidirectional by Default**: All sync operations are two-way unless you explicitly specify `--direction to-jira` or `--direction from-jira`. This keeps both systems synchronized automatically.
+
 **Granular Control**: Unlike simple epic import/export, this command supports cherry-picking individual stories, bugs, and tasks for maximum flexibility.

package/plugins/specweave-jira/skills/jira-resource-validator/SKILL.md

@@ -41,22 +41,34 @@ JIRA_PROJECT=PROJECTKEY
 JIRA_BOARDS=1,2,3  # IDs (if exist) OR names (if creating)
 ```
 
-### Two Modes for JIRA_BOARDS
+### Smart Per-Board Detection (Mixed Mode Support!)
 
-**Mode 1: Board IDs** (boards already exist):
+**The system is smart enough to handle ANY combination of IDs and names:**
+
+**All IDs** (validate existing boards):
 ```bash
 JIRA_BOARDS=1,2,3
 ```
-- System validates these IDs exist in Jira
-- If any ID doesn't exist, prompts to fix configuration
+→ Validates boards 1, 2, 3 exist
 
-**Mode 2: Board Names** (boards need to be created):
+**All Names** (create new boards):
 ```bash
 JIRA_BOARDS=Frontend,Backend,Mobile
 ```
-- System detects names (non-numeric)
-- Creates boards automatically
-- Updates .env with actual IDs: `JIRA_BOARDS=101,102,103`
+→ Creates 3 boards, updates .env with IDs: `JIRA_BOARDS=101,102,103`
+
+**Mixed IDs and Names** (smart handling!):
+```bash
+JIRA_BOARDS=101,102,QA,Dashboard
+```
+→ Validates 101, 102 exist
+→ Creates "QA" and "Dashboard" boards
+→ Updates .env: `JIRA_BOARDS=101,102,103,104` (all IDs!)
+
+**How it works**: Each entry is checked individually:
+- Numeric (e.g., "123") → Validate ID exists
+- Non-numeric (e.g., "QA") → Create board with that name
+- After creation, .env is updated with ALL board IDs
 
 ## Validation Flow
 
@@ -107,9 +119,9 @@ Enter project name: My New Project
 ✅ Project created: PROJECTKEY (ID: 10005)
 ```
 
-### Step 2: Board Validation
+### Step 2: Board Validation (Per-Board Smart Detection)
 
-**Scenario A: Board IDs Provided** (numeric values):
+**Scenario A: All Board IDs** (all numeric):
 ```bash
 JIRA_BOARDS=1,2,3
 ```
@@ -117,40 +129,53 @@ JIRA_BOARDS=1,2,3
 **Validation**:
 ```
 Checking boards: 1,2,3...
+  ✅ Board 1: Frontend Board (exists)
+  ✅ Board 2: Backend Board (exists)
+  ⚠️  Board 3: Not found
 
-Board 1: ✅ Exists (Frontend Board)
-Board 2: ✅ Exists (Backend Board)
-Board 3: ❌ Not found
-
-⚠️  Boards not found: 3
-
-Options:
-1. Remove board 3 from configuration
-2. Replace with correct board ID
-3. Create new board
-
-Your choice [1]:
+⚠️  Issues found: 1 board(s)
 ```
 
-**Scenario B: Board Names Provided** (non-numeric):
+**Scenario B: All Board Names** (all non-numeric):
 ```bash
 JIRA_BOARDS=Frontend,Backend,Mobile
 ```
 
 **Auto-creation**:
 ```
-📦 Creating boards from names...
+Checking boards: Frontend,Backend,Mobile...
+  📦 Creating board: Frontend...
+  ✅ Created: Frontend (ID: 101)
+  📦 Creating board: Backend...
+  ✅ Created: Backend (ID: 102)
+  📦 Creating board: Mobile...
+  ✅ Created: Mobile (ID: 103)
 
-Creating board: Frontend in project PROJECTKEY...
-✅ Board created: Frontend (ID: 101)
+📝 Updating .env with board IDs...
+✅ Updated JIRA_BOARDS: 101,102,103
 
-Creating board: Backend in project PROJECTKEY...
-✅ Board created: Backend (ID: 102)
+✅ All boards validated/created successfully
+```
 
-Creating board: Mobile in project PROJECTKEY...
-✅ Board created: Mobile (ID: 103)
+**Scenario C: Mixed IDs and Names** (SMART!):
+```bash
+JIRA_BOARDS=101,102,QA,Dashboard
+```
 
-✅ Updated .env: JIRA_BOARDS=101,102,103
+**Smart handling**:
+```
+Checking boards: 101,102,QA,Dashboard...
+  ✅ Board 101: Frontend Board (exists)
+  ✅ Board 102: Backend Board (exists)
+  📦 Creating board: QA...
+  ✅ Created: QA (ID: 103)
+  📦 Creating board: Dashboard...
+  ✅ Created: Dashboard (ID: 104)
+
+📝 Updating .env with board IDs...
+✅ Updated JIRA_BOARDS: 101,102,103,104
+
+✅ All boards validated/created successfully
 ```
 
 ## Usage Examples
@@ -303,39 +328,50 @@ npx tsx src/utils/external-resource-validator.ts
 }
 ```
 
-## Smart Board Creation Logic
+## Smart Board Creation Logic (Per-Board Detection)
 
 ### Detection Algorithm
 
 ```typescript
 // Parse JIRA_BOARDS from .env
-const boardsConfig = "Frontend,Backend,Mobile";
-const boardIds = boardsConfig.split(',').map(b => b.trim());
-
-// Check if all values are numeric
-const isNumeric = boardIds.every(b => /^\d+$/.test(b));
-
-if (isNumeric) {
-  // Mode 1: Board IDs - validate existence
-  for (const boardId of boardIds) {
-    const exists = await checkBoard(parseInt(boardId));
-    if (!exists) {
-      console.error(`Board ${boardId} not found`);
+const boardsConfig = "101,102,QA,Dashboard"; // Mixed!
+const boardEntries = boardsConfig.split(',').map(b => b.trim());
+const finalBoardIds = [];
+
+// Check EACH board individually
+for (const entry of boardEntries) {
+  const isNumeric = /^\d+$/.test(entry);
+
+  if (isNumeric) {
+    // Entry is a board ID - validate it exists
+    const boardId = parseInt(entry);
+    const board = await checkBoard(boardId);
+    if (board) {
+      console.log(`✅ Board ${boardId}: ${board.name} (exists)`);
+      finalBoardIds.push(boardId);
+    } else {
+      console.error(`⚠️  Board ${boardId}: Not found`);
     }
+  } else {
+    // Entry is a board name - create it
+    console.log(`📦 Creating board: ${entry}...`);
+    const board = await createBoard(entry, projectKey);
+    console.log(`✅ Created: ${entry} (ID: ${board.id})`);
+    finalBoardIds.push(board.id);
   }
-} else {
-  // Mode 2: Board names - create boards
-  const createdBoardIds = [];
-  for (const boardName of boardIds) {
-    const board = await createBoard(boardName, projectKey);
-    createdBoardIds.push(board.id);
-  }
+}
 
-  // Update .env with actual IDs
-  updateEnv({ JIRA_BOARDS: createdBoardIds.join(',') });
+// Update .env if any boards were created
+if (createdBoardIds.length > 0) {
+  updateEnv({ JIRA_BOARDS: finalBoardIds.join(',') });
 }
 ```
 
+**Key improvement**: Per-board detection instead of all-or-nothing!
+- `JIRA_BOARDS=1,2,3` → Validates all IDs
+- `JIRA_BOARDS=A,B,C` → Creates all boards
+- `JIRA_BOARDS=1,2,C` → Validates 1,2, creates C (mixed!)
+
 ### Board Creation API
 
 **Jira REST API** (v3):
@@ -346,7 +382,11 @@ Content-Type: application/json
 {
   "name": "Frontend Board",
   "type": "scrum",
-  "filterId": 10000  # Filter for project issues
+  "filterId": 10000,  # Filter for project issues
+  "location": {
+    "type": "project",
+    "projectKeyOrId": "PROJECTKEY"  # CRITICAL: Associates board with project
+  }
 }
 
 Response:
@@ -357,6 +397,8 @@ Response:
 }
 ```
 
+**IMPORTANT**: The `location` field is **MANDATORY** to associate the board with a project. Without it, Jira creates the board but leaves it detached, requiring manual connection via the UI.
+
 **Filter creation** (required for board):
 ```bash
 POST /rest/api/3/filter
@@ -375,7 +417,7 @@ Response:
 
 ## Configuration Examples
 
-### Example 1: Create Boards by Name
+### Example 1: All Names (Create Boards)
 
 **Before** (`.env`):
 ```bash
@@ -394,7 +436,7 @@ JIRA_BOARDS=101,102,103,104
 - Created 4 boards in Jira
 - Updated .env with actual board IDs
 
-### Example 2: Validate Existing Board IDs
+### Example 2: All IDs (Validate Existing)
 
 **Before** (`.env`):
 ```bash
@@ -413,7 +455,28 @@ JIRA_BOARDS=1,2,3
 - Validated all boards exist
 - No changes needed
 
-### Example 3: Fix Invalid Project
+### Example 3: Mixed IDs and Names (SMART!)
+
+**Before** (`.env`):
+```bash
+JIRA_PROJECT=PROJ
+JIRA_BOARDS=101,102,QA,Dashboard
+```
+
+**After validation**:
+```bash
+JIRA_PROJECT=PROJ
+JIRA_BOARDS=101,102,103,104
+```
+
+**What happened**:
+- Validated boards 101, 102 exist
+- Created "QA" board (got ID 103)
+- Created "Dashboard" board (got ID 104)
+- Updated .env with ALL board IDs
+- **This is the key feature** - you can mix existing IDs with new board names!
+
+### Example 4: Fix Invalid Project
 
 **Before** (`.env`):
 ```bash