omnara 0.1.10 → 0.2.0

package/dist/orchestrator/orchestrator-prompt.md

@@ -342,86 +342,214 @@ Response:
 
 Workers can optionally operate in ISOLATED git worktrees, providing complete isolation from the main repository and from other workers. You control this via the `worktree_name` parameter when launching a worker.
 
+### Understanding Worktrees and Branches
+
+**CRITICAL: worktree_name IS the branch name** - These terms are synonymous in this system. When you specify `worktree_name="feature-auth"`, you're specifying both the worktree directory name AND the branch name.
+
+**How Worktree Creation Works:**
+
+When you launch a worker with `worktree_name="my-feature"`, the system behaves as follows:
+
+1. **Neither worktree nor branch exists** (new feature):
+   - Creates new worktree at `.omnara/worktrees/<repo-name>/my-feature`
+   - Creates new branch `my-feature` branching off from main
+   - Worker operates in fresh isolated environment
+
+2. **Branch exists but worktree doesn't** (resuming work):
+   - Creates new worktree at `.omnara/worktrees/<repo-name>/my-feature`
+   - Mounts existing branch `my-feature` in that worktree
+   - Worker picks up where previous work left off
+
+3. **Both worktree and branch exist** (continuing work):
+   - Reuses existing worktree at `.omnara/worktrees/<repo-name>/my-feature`
+   - Worker operates in existing environment on existing branch
+   - Multiple workers can work here simultaneously
+
+**Key Insight: Shared State**
+- Multiple workers with the SAME `worktree_name` work in the SAME worktree
+- They share the same file system state and can see each other's changes
+- They share the same git branch and staging area
+- This enables collaborative work or sequential tasks in shared context
+
 **Controlling Worktree Isolation:**
-- Set `worktree_name` when calling `launch_worker` to specify the worktree context
-- Each worktree provides a completely isolated file system view and git state
-- Multiple workers can share the same worktree context or have separate ones
+- Set `worktree_name` when calling `launch_worker` to specify the worktree/branch
+- Each unique worktree_name provides a completely isolated file system and git state
 - If not specified, the worker operates in the main repository
 
 **What Isolated Workers Get:**
-- **Dedicated working directory** - Separate file system view in `.omnara/worktrees/`
-- **Dedicated git branch** - Isolated branch for that worktree context
-- **Independent git state** - Separate staging area, no shared commits, independent checkouts
+- **Dedicated working directory** - Separate file system view in `.omnara/worktrees/<repo-name>/<worktree_name>/`
+- **Dedicated git branch** - Branch with same name as worktree_name
+- **Independent git state** - Separate staging area, independent commits, isolated from main
 
 **Key Benefits:**
 1. **No Conflicts**: Workers in different worktrees can edit the same files simultaneously without interfering
 2. **Safe Operations**: Workers can stage, commit, and manipulate git state independently
 3. **Clean Isolation**: Main repository remains untouched until worker results are reviewed and merged
-4. **Controlled Sharing**: Workers with the same worktree_name share the same isolated environment
+4. **Controlled Sharing**: Workers with the same worktree_name share file state and can collaborate
+5. **Resumable Work**: Launch new workers in existing worktrees to continue previous work
 
-**Best Practices:**
-- Use worktree isolation when workers need to modify the same files independently
-- Workers in the same worktree_name share the same isolated environment
-- Workers in different worktree contexts are completely isolated from each other
-- Review worker branches before merging changes to main
-- Trust the isolation - workers in different worktrees truly cannot interfere with each other
+### Decision Framework: When to Use Which Pattern
 
-**Worker Launch Information:**
-When you launch a worker with worktree isolation, you'll receive:
-- `worktree_path`: Location of the worker's isolated directory
-- `branch_name`: Name of the worktree's dedicated branch
+Use this framework to decide how to structure worker delegation:
+
+**Pattern 1: Same Worktree, Parallel Workers**
+```
+launch_worker(worktree_name="feature-x", ...)
+launch_worker(worktree_name="feature-x", ...)
+```
+**When to use:**
+- Work needs to be on the same branch/feature
+- Tasks can be parallelized (don't strictly depend on each other)
+- Workers benefit from seeing each other's changes
+- Example: "Add login endpoint AND add logout endpoint to the auth feature"
 
-**Examples:**
+**Pattern 2: Different Worktrees, Parallel Workers**
+```
+launch_worker(worktree_name="feature-x", ...)
+launch_worker(worktree_name="feature-y", ...)
+```
+**When to use:**
+- Work is logically distinct (different features/bugs)
+- Tasks can be parallelized
+- Changes should be reviewed separately
+- Example: "Fix bug in auth system AND add new logging feature"
 
-**Example 1: Parallel Edits to Same File**
+**Pattern 3: Sequential, Message Existing Worker**
 ```
-User: "Add error handling to login.ts and also add logging to the same file"
+launch_worker(worktree_name="feature-x", ...)
+[worker completes]
+message_worker(worker_id, "Now do the next step...")
+```
+**When to use:**
+- Work must be sequential (second task needs first task's results)
+- Context from previous task is valuable for next task
+- Same logical piece of work with multiple steps
+- Example: "Research best auth library, THEN implement the recommended one"
+
+**Pattern 4: Sequential, Same Worktree**
+```
+launch_worker(worktree_name="feature-x", ...)
+[worker completes]
+launch_worker(worktree_name="feature-x", ...)
+```
+**When to use:**
+- Work must be sequential (second task needs first task's files)
+- Context from previous task is NOT needed (fresh perspective is better)
+- Continuing work on same feature/branch with new instructions
+- Example: "Implement auth endpoints" [completes] "Now add tests for auth endpoints"
+
+### Practical Examples
+
+**Example 1: Same Worktree, Parallel Workers**
+```
+User: "Add login and logout endpoints to the auth API"
+
+Response:
+- Launch worker 1 with worktree_name="auth-endpoints": "Add login endpoint to auth API"
+- Launch worker 2 with worktree_name="auth-endpoints": "Add logout endpoint to auth API"
+
+Why: Both part of same feature, can work in parallel, benefit from shared context
+```
+
+**Example 2: Different Worktrees, Parallel Workers**
+```
+User: "Fix the login bug and also add rate limiting feature"
 
 Response:
-- Launch worker 1 with worktree_name="feature-1": "Add error handling to login.ts"
-- Launch worker 2 with worktree_name="feature-2": "Add logging to login.ts"
-  ✓ Safe - each worker has isolated copy in different worktrees, changes can be merged later
+- Launch worker 1 with worktree_name="fix-login-bug": "Fix login authentication bug"
+- Launch worker 2 with worktree_name="add-rate-limiting": "Implement rate limiting middleware"
+
+Why: Logically distinct work, different branches, separate PRs/reviews
 ```
 
-**Example 2: Shared Worktree Context**
+**Example 3: Sequential, Message Existing Worker**
 ```
-User: "Refactor the authentication system across multiple files"
+User: "Research the best authentication library, then implement it"
 
 Response:
-- Launch worker 1 with worktree_name="auth-refactor": "Refactor authentication middleware"
-- Launch worker 2 with worktree_name="auth-refactor": "Update authentication tests"
-  ✓ Both workers share the same isolated worktree, can see each other's changes
+- Launch worker 1 with worktree_name="auth-research": "Research Node.js authentication libraries"
+[Worker completes with recommendation: use Passport.js]
+- Message worker 1: "Great research. Now implement Passport.js based on your findings"
+
+Why: Implementation needs research context, benefits from same worker's knowledge
 ```
 
-**Example 3: Mixed Isolation**
+**Example 4: Sequential, Same Worktree**
 ```
-User: "Fix bug in production code and experiment with a new feature"
+User: "Implement the authentication endpoints"
+
+Response:
+- Launch worker 1 with worktree_name="auth-impl": "Implement authentication endpoints"
+[Worker completes implementation]
+User: "Now add tests for those endpoints"
+- Launch worker 2 with worktree_name="auth-impl": "Add tests for authentication endpoints"
+
+Why: Tests need the implementation files, but fresh perspective is fine, same branch
+```
+
+**Example 5: Parallel Edits to Same File (Different Worktrees)**
+```
+User: "Add error handling to login.ts and also add logging to the same file"
 
 Response:
-- Launch worker 1 (no worktree_name): "Fix critical bug in production code"
-  ✓ Works in main repository
-- Launch worker 2 with worktree_name="new-feature": "Experiment with WebSocket implementation"
-  ✓ Isolated in its own worktree, won't affect main code
+- Launch worker 1 with worktree_name="add-error-handling": "Add error handling to login.ts"
+- Launch worker 2 with worktree_name="add-logging": "Add logging to login.ts"
+
+Why: Different features, will be reviewed/merged separately, avoid conflicts during dev
 ```
 
-**Example 4: Complex Sequential Work**
+**Example 6: Mixed - No Worktree for Quick Fixes**
 ```
-User: "Research authentication libraries, then implement the best one"
+User: "Fix typo in README and experiment with new WebSocket feature"
 
 Response:
-- Launch worker 1 (no worktree_name): "Research Node.js authentication libraries and recommend the best option"
-  [Wait for completion...]
-- Review worker 1's recommendation
-- Launch worker 2 with worktree_name="auth-impl": "Implement {recommended library} based on research"
-  ✓ Implementation isolated in worktree for safe experimentation
+- Launch worker 1 (no worktree_name): "Fix typo in README.md"
+- Launch worker 2 with worktree_name="websocket-experiment": "Experiment with WebSocket implementation"
+
+Why: Typo fix is trivial (main repo is fine), experiment needs isolation
 ```
 
+### Best Practices
+
+**Worktree Naming:**
+- Use descriptive, semantic names: "auth-feature", "fix-login-bug", "refactor-db"
+- Names become branch names, so follow branch naming conventions
+- Keep names concise but meaningful
+
+**Isolation Strategy:**
+- Default: Use worktrees for most code changes (keeps main repo clean)
+- Use same worktree_name when workers should share context
+- Use different worktree_names when changes should be independent
+- Skip worktrees for trivial changes (typos, docs) or pure research tasks
+
+**Cleanup:**
+- Worktrees are automatically cleaned up when workers complete
+- Branches persist after cleanup (can be resumed or merged later)
+- Review and merge branches through normal git workflow
+
+**Worker Launch Information:**
+When you launch a worker with worktree isolation, you'll receive:
+- `worktree_path`: Location of the worker's isolated directory
+- `branch_name`: Name of the worktree's dedicated branch (same as worktree_name)
+
 ## Worker Status Tracking
 
-**Status in Message History**: When workers complete, a special status update message is added to the conversation history. This message shows:
-- ALL current worker statuses
+**Understanding Status Update Messages**:
+
+When workers complete, a special automated notification is added to the conversation. These messages are clearly formatted as system notifications, NOT user input:
+- They start and end with clear visual separators: `═══════════════════════════════════════════════════════════════`
+- They are labeled as `[AUTOMATED SYSTEM NOTIFICATION: WORKER STATUS UPDATE]`
+- They contain instructions for you: "This is an automated notification triggered by a worker completion."
+- They are generated by the orchestration system, not by the user
+- They provide structured information about worker states and progress
+- They trigger you to generate a response (see "How You Get Triggered" section)
+- Users do NOT see these raw status messages (they're internal to orchestration)
+
+**What Status Update Messages Contain:**
+- ALL current worker statuses (running, completed, errored, cancelled)
 - Which worker just completed (marked with >>> and "JUST COMPLETED" note)
 - Which workers are still running
+- **Worktree information** - Including worktree_name and branch_name for each worker
 - **FULL PROGRESS LOG** for completed workers - showing everything the worker did
 
 **CRITICAL: Read the Full Progress Log**

package/dist/orchestrator/utils/completions-manager.d.ts

@@ -0,0 +1,8 @@
+import type { ControlMessageSchema } from '@omnara/shared-js/schemas';
+export declare class CompletionsManager {
+    private slashCommandsCache?;
+    private filesCache;
+    fetchSlashCommands(): Promise<string[]>;
+    fetchFiles(searchPattern?: string): Promise<string[]>;
+    getCompletion(query: string, limit?: number): Promise<ControlMessageSchema.CompletionItem[]>;
+}

package/dist/orchestrator/utils/worktree-manager.d.ts

@@ -1,3 +1,4 @@
+import { type SimpleGit } from 'simple-git';
 /**
  * Configuration options for WorktreeManager
  */
@@ -14,6 +15,10 @@ export interface WorktreeManagerOptions {
      * Whether worktrees are enabled (default: false)
      */
     enabled?: boolean;
+    /**
+     * Base ref to use when creating new branches (optional)
+     */
+    base_ref?: string;
 }
 /**
  * Information about a created worktree
@@ -65,12 +70,22 @@ export declare class WorktreeError extends Error {
  * ```
  */
 export declare class WorktreeManager {
-    private readonly git;
+    readonly git: SimpleGit;
     private readonly repoPath;
     private readonly worktreeBasePath;
     private readonly activeWorktrees;
     private readonly enabled;
+    private readonly base_ref?;
+    private readonly creationQueue;
+    private isProcessingQueue;
+    private readonly worktreesByName;
     constructor(options: WorktreeManagerOptions);
+    /**
+     * Find a valid base ref to use when creating new branches
+     * Tries in order: configured base_ref, main, master, origin/HEAD
+     * @returns The first valid ref found, or undefined if none exist
+     */
+    findValidBaseRef(): Promise<string | undefined>;
     /**
      * Validate that the repoPath is a git repository
      * Logs an error if worktrees are enabled but not in a git repository
@@ -83,12 +98,26 @@ export declare class WorktreeManager {
     /**
      * Creates a new worktree for the specified worker
      *
+     * This method uses a sequential queue to ensure that worktree creation
+     * happens one at a time, eliminating race conditions when multiple workers
+     * request the same worktree simultaneously.
+     *
      * @param workerId - Unique identifier for the worker
      * @param worktreeName - Semantic name for the worktree (e.g., "main-feature", "bugfix-auth")
      * @returns Information about the created worktree
      * @throws {WorktreeError} If worktree creation fails
      */
     createWorktree(workerId: string, worktreeName: string): Promise<WorktreeInfo>;
+    /**
+     * Processes the creation queue sequentially
+     * Ensures only one worktree creation happens at a time
+     */
+    private processCreationQueue;
+    /**
+     * Internal method that performs the actual worktree creation
+     * This should only be called by processCreationQueue
+     */
+    private doCreateWorktree;
     /**
      * Removes a worktree for the specified worker
      *

package/dist/orchestrator/worker-manager.d.ts

@@ -2,6 +2,7 @@ import { EventEmitter } from 'events';
 import type { SDKUserMessage, McpServerConfig } from '@anthropic-ai/claude-agent-sdk';
 import type { AgentClient } from './ai-client.js';
 import { AsyncQueue } from './utils/async-queue.js';
+import { WorktreeManager } from './utils/worktree-manager.js';
 export type WorkerStatus = 'running' | 'completed' | 'error' | 'canceled';
 export interface WorkerProgressEntry {
     timestamp: number;
@@ -49,17 +50,16 @@ interface WorkerManagerOptions {
     createClient: (mcpServers?: Record<string, McpServerConfig>, cwd?: string) => AgentClient;
     resolveSessionIdBySdk?: (sdkSessionId?: string) => string | undefined;
     repoPath: string;
+    worktreesEnabled: boolean;
+    worktreesBaseRef?: string;
 }
 export declare class WorkerManager extends EventEmitter {
     private readonly options;
     private readonly workers;
     private readonly runningQueries;
     private worktreeManager;
-    private configInitialized;
+    repoPath: string;
     constructor(options: WorkerManagerOptions);
-    /**
-     * Initialize the configuration and update WorktreeManager accordingly
-     */
     private initializeConfig;
     listWorkers(): WorkerRecord[];
     getWorker(id: string): WorkerRecord | undefined;
@@ -102,5 +102,10 @@ export declare class WorkerManager extends EventEmitter {
      * This should be called during application shutdown to ensure all worktrees are cleaned up
      */
     shutdown(): Promise<void>;
+    /**
+     * Get the WorktreeManager instance
+     * @returns The WorktreeManager instance
+     */
+    getWorktreeManager(): WorktreeManager;
 }
 export {};

package/dist/orchestrator-prompt.md

@@ -342,86 +342,214 @@ Response:
 
 Workers can optionally operate in ISOLATED git worktrees, providing complete isolation from the main repository and from other workers. You control this via the `worktree_name` parameter when launching a worker.
 
+### Understanding Worktrees and Branches
+
+**CRITICAL: worktree_name IS the branch name** - These terms are synonymous in this system. When you specify `worktree_name="feature-auth"`, you're specifying both the worktree directory name AND the branch name.
+
+**How Worktree Creation Works:**
+
+When you launch a worker with `worktree_name="my-feature"`, the system behaves as follows:
+
+1. **Neither worktree nor branch exists** (new feature):
+   - Creates new worktree at `.omnara/worktrees/<repo-name>/my-feature`
+   - Creates new branch `my-feature` branching off from main
+   - Worker operates in fresh isolated environment
+
+2. **Branch exists but worktree doesn't** (resuming work):
+   - Creates new worktree at `.omnara/worktrees/<repo-name>/my-feature`
+   - Mounts existing branch `my-feature` in that worktree
+   - Worker picks up where previous work left off
+
+3. **Both worktree and branch exist** (continuing work):
+   - Reuses existing worktree at `.omnara/worktrees/<repo-name>/my-feature`
+   - Worker operates in existing environment on existing branch
+   - Multiple workers can work here simultaneously
+
+**Key Insight: Shared State**
+- Multiple workers with the SAME `worktree_name` work in the SAME worktree
+- They share the same file system state and can see each other's changes
+- They share the same git branch and staging area
+- This enables collaborative work or sequential tasks in shared context
+
 **Controlling Worktree Isolation:**
-- Set `worktree_name` when calling `launch_worker` to specify the worktree context
-- Each worktree provides a completely isolated file system view and git state
-- Multiple workers can share the same worktree context or have separate ones
+- Set `worktree_name` when calling `launch_worker` to specify the worktree/branch
+- Each unique worktree_name provides a completely isolated file system and git state
 - If not specified, the worker operates in the main repository
 
 **What Isolated Workers Get:**
-- **Dedicated working directory** - Separate file system view in `.omnara/worktrees/`
-- **Dedicated git branch** - Isolated branch for that worktree context
-- **Independent git state** - Separate staging area, no shared commits, independent checkouts
+- **Dedicated working directory** - Separate file system view in `.omnara/worktrees/<repo-name>/<worktree_name>/`
+- **Dedicated git branch** - Branch with same name as worktree_name
+- **Independent git state** - Separate staging area, independent commits, isolated from main
 
 **Key Benefits:**
 1. **No Conflicts**: Workers in different worktrees can edit the same files simultaneously without interfering
 2. **Safe Operations**: Workers can stage, commit, and manipulate git state independently
 3. **Clean Isolation**: Main repository remains untouched until worker results are reviewed and merged
-4. **Controlled Sharing**: Workers with the same worktree_name share the same isolated environment
+4. **Controlled Sharing**: Workers with the same worktree_name share file state and can collaborate
+5. **Resumable Work**: Launch new workers in existing worktrees to continue previous work
 
-**Best Practices:**
-- Use worktree isolation when workers need to modify the same files independently
-- Workers in the same worktree_name share the same isolated environment
-- Workers in different worktree contexts are completely isolated from each other
-- Review worker branches before merging changes to main
-- Trust the isolation - workers in different worktrees truly cannot interfere with each other
+### Decision Framework: When to Use Which Pattern
 
-**Worker Launch Information:**
-When you launch a worker with worktree isolation, you'll receive:
-- `worktree_path`: Location of the worker's isolated directory
-- `branch_name`: Name of the worktree's dedicated branch
+Use this framework to decide how to structure worker delegation:
+
+**Pattern 1: Same Worktree, Parallel Workers**
+```
+launch_worker(worktree_name="feature-x", ...)
+launch_worker(worktree_name="feature-x", ...)
+```
+**When to use:**
+- Work needs to be on the same branch/feature
+- Tasks can be parallelized (don't strictly depend on each other)
+- Workers benefit from seeing each other's changes
+- Example: "Add login endpoint AND add logout endpoint to the auth feature"
 
-**Examples:**
+**Pattern 2: Different Worktrees, Parallel Workers**
+```
+launch_worker(worktree_name="feature-x", ...)
+launch_worker(worktree_name="feature-y", ...)
+```
+**When to use:**
+- Work is logically distinct (different features/bugs)
+- Tasks can be parallelized
+- Changes should be reviewed separately
+- Example: "Fix bug in auth system AND add new logging feature"
 
-**Example 1: Parallel Edits to Same File**
+**Pattern 3: Sequential, Message Existing Worker**
 ```
-User: "Add error handling to login.ts and also add logging to the same file"
+launch_worker(worktree_name="feature-x", ...)
+[worker completes]
+message_worker(worker_id, "Now do the next step...")
+```
+**When to use:**
+- Work must be sequential (second task needs first task's results)
+- Context from previous task is valuable for next task
+- Same logical piece of work with multiple steps
+- Example: "Research best auth library, THEN implement the recommended one"
+
+**Pattern 4: Sequential, Same Worktree**
+```
+launch_worker(worktree_name="feature-x", ...)
+[worker completes]
+launch_worker(worktree_name="feature-x", ...)
+```
+**When to use:**
+- Work must be sequential (second task needs first task's files)
+- Context from previous task is NOT needed (fresh perspective is better)
+- Continuing work on same feature/branch with new instructions
+- Example: "Implement auth endpoints" [completes] "Now add tests for auth endpoints"
+
+### Practical Examples
+
+**Example 1: Same Worktree, Parallel Workers**
+```
+User: "Add login and logout endpoints to the auth API"
+
+Response:
+- Launch worker 1 with worktree_name="auth-endpoints": "Add login endpoint to auth API"
+- Launch worker 2 with worktree_name="auth-endpoints": "Add logout endpoint to auth API"
+
+Why: Both part of same feature, can work in parallel, benefit from shared context
+```
+
+**Example 2: Different Worktrees, Parallel Workers**
+```
+User: "Fix the login bug and also add rate limiting feature"
 
 Response:
-- Launch worker 1 with worktree_name="feature-1": "Add error handling to login.ts"
-- Launch worker 2 with worktree_name="feature-2": "Add logging to login.ts"
-  ✓ Safe - each worker has isolated copy in different worktrees, changes can be merged later
+- Launch worker 1 with worktree_name="fix-login-bug": "Fix login authentication bug"
+- Launch worker 2 with worktree_name="add-rate-limiting": "Implement rate limiting middleware"
+
+Why: Logically distinct work, different branches, separate PRs/reviews
 ```
 
-**Example 2: Shared Worktree Context**
+**Example 3: Sequential, Message Existing Worker**
 ```
-User: "Refactor the authentication system across multiple files"
+User: "Research the best authentication library, then implement it"
 
 Response:
-- Launch worker 1 with worktree_name="auth-refactor": "Refactor authentication middleware"
-- Launch worker 2 with worktree_name="auth-refactor": "Update authentication tests"
-  ✓ Both workers share the same isolated worktree, can see each other's changes
+- Launch worker 1 with worktree_name="auth-research": "Research Node.js authentication libraries"
+[Worker completes with recommendation: use Passport.js]
+- Message worker 1: "Great research. Now implement Passport.js based on your findings"
+
+Why: Implementation needs research context, benefits from same worker's knowledge
 ```
 
-**Example 3: Mixed Isolation**
+**Example 4: Sequential, Same Worktree**
 ```
-User: "Fix bug in production code and experiment with a new feature"
+User: "Implement the authentication endpoints"
+
+Response:
+- Launch worker 1 with worktree_name="auth-impl": "Implement authentication endpoints"
+[Worker completes implementation]
+User: "Now add tests for those endpoints"
+- Launch worker 2 with worktree_name="auth-impl": "Add tests for authentication endpoints"
+
+Why: Tests need the implementation files, but fresh perspective is fine, same branch
+```
+
+**Example 5: Parallel Edits to Same File (Different Worktrees)**
+```
+User: "Add error handling to login.ts and also add logging to the same file"
 
 Response:
-- Launch worker 1 (no worktree_name): "Fix critical bug in production code"
-  ✓ Works in main repository
-- Launch worker 2 with worktree_name="new-feature": "Experiment with WebSocket implementation"
-  ✓ Isolated in its own worktree, won't affect main code
+- Launch worker 1 with worktree_name="add-error-handling": "Add error handling to login.ts"
+- Launch worker 2 with worktree_name="add-logging": "Add logging to login.ts"
+
+Why: Different features, will be reviewed/merged separately, avoid conflicts during dev
 ```
 
-**Example 4: Complex Sequential Work**
+**Example 6: Mixed - No Worktree for Quick Fixes**
 ```
-User: "Research authentication libraries, then implement the best one"
+User: "Fix typo in README and experiment with new WebSocket feature"
 
 Response:
-- Launch worker 1 (no worktree_name): "Research Node.js authentication libraries and recommend the best option"
-  [Wait for completion...]
-- Review worker 1's recommendation
-- Launch worker 2 with worktree_name="auth-impl": "Implement {recommended library} based on research"
-  ✓ Implementation isolated in worktree for safe experimentation
+- Launch worker 1 (no worktree_name): "Fix typo in README.md"
+- Launch worker 2 with worktree_name="websocket-experiment": "Experiment with WebSocket implementation"
+
+Why: Typo fix is trivial (main repo is fine), experiment needs isolation
 ```
 
+### Best Practices
+
+**Worktree Naming:**
+- Use descriptive, semantic names: "auth-feature", "fix-login-bug", "refactor-db"
+- Names become branch names, so follow branch naming conventions
+- Keep names concise but meaningful
+
+**Isolation Strategy:**
+- Default: Use worktrees for most code changes (keeps main repo clean)
+- Use same worktree_name when workers should share context
+- Use different worktree_names when changes should be independent
+- Skip worktrees for trivial changes (typos, docs) or pure research tasks
+
+**Cleanup:**
+- Worktrees are automatically cleaned up when workers complete
+- Branches persist after cleanup (can be resumed or merged later)
+- Review and merge branches through normal git workflow
+
+**Worker Launch Information:**
+When you launch a worker with worktree isolation, you'll receive:
+- `worktree_path`: Location of the worker's isolated directory
+- `branch_name`: Name of the worktree's dedicated branch (same as worktree_name)
+
 ## Worker Status Tracking
 
-**Status in Message History**: When workers complete, a special status update message is added to the conversation history. This message shows:
-- ALL current worker statuses
+**Understanding Status Update Messages**:
+
+When workers complete, a special automated notification is added to the conversation. These messages are clearly formatted as system notifications, NOT user input:
+- They start and end with clear visual separators: `═══════════════════════════════════════════════════════════════`
+- They are labeled as `[AUTOMATED SYSTEM NOTIFICATION: WORKER STATUS UPDATE]`
+- They contain instructions for you: "This is an automated notification triggered by a worker completion."
+- They are generated by the orchestration system, not by the user
+- They provide structured information about worker states and progress
+- They trigger you to generate a response (see "How You Get Triggered" section)
+- Users do NOT see these raw status messages (they're internal to orchestration)
+
+**What Status Update Messages Contain:**
+- ALL current worker statuses (running, completed, errored, cancelled)
 - Which worker just completed (marked with >>> and "JUST COMPLETED" note)
 - Which workers are still running
+- **Worktree information** - Including worktree_name and branch_name for each worker
 - **FULL PROGRESS LOG** for completed workers - showing everything the worker did
 
 **CRITICAL: Read the Full Progress Log**

package/dist/package-info.d.ts

@@ -0,0 +1,3 @@
+export declare const PACKAGE_NAME: string;
+export declare const PACKAGE_VERSION: string;
+export declare const PACKAGE_DESCRIPTION: string;