worktree-flow 0.0.16 → 0.0.17

package/README.md

@@ -56,6 +56,10 @@ Create a new branch across selected repos. Interactively select which repos to i
 
 Checkout an existing branch. Fetches all repos, detects which have the branch, and creates worktrees.
 
+### `flow add [name]`
+
+Add repos to an existing workspace. Discovers available repos not yet in the workspace, presents an interactive picker, creates worktrees with new branches, copies config files, and runs post-checkout commands. Auto-detects the workspace from the current directory, or specify a branch name explicitly.
+
 ### `flow pull`
 
 Pull latest changes for all repos in the current workspace. Run from anywhere inside a workspace.
@@ -126,6 +130,22 @@ Repos with per-repo commands use those; others fall back to the global `post-che
 
 When tmux is enabled, post-checkout commands run in the corresponding tmux panes instead of executing directly. This lets you see the output in real-time within your tmux session.
 
+### Repo-level configuration
+
+Individual repos can define a `flow-config.json` at their root to override global settings:
+
+```json
+{
+  "copy-files": ".env,.env.local",
+  "post-checkout": "yarn install"
+}
+```
+
+Both fields are optional. Precedence (highest to lowest):
+
+- **post-checkout**: repo's `flow-config.json` > global `post-checkout`
+- **copy-files**: repo's `flow-config.json` > global `copy-files`
+
 ## AGENTS.md
 
 If an `AGENTS.md` file exists at the root of your source-path, it will be copied into each workspace. This is useful for providing AI coding agents with context about your multi-repo setup.

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import { registerConfigCommand } from './commands/config.js';
+import { registerAddCommand } from './commands/add.js';
 import { registerBranchCommand } from './commands/branch.js';
 import { registerCheckoutCommand } from './commands/checkout.js';
 import { registerListCommand } from './commands/list.js';
@@ -18,6 +19,7 @@ program
     .description('Manage git worktrees across a poly-repo environment')
     .version('0.1.0');
 registerConfigCommand(program);
+registerAddCommand(program);
 registerBranchCommand(program);
 registerCheckoutCommand(program);
 registerListCommand(program);

package/dist/commands/add.js

@@ -0,0 +1,120 @@
+import path from 'node:path';
+import checkbox, { Separator } from '@inquirer/checkbox';
+import input from '@inquirer/input';
+import confirm from '@inquirer/confirm';
+import chalk from 'chalk';
+import { createServices } from '../lib/services.js';
+import { createUseCases } from '../usecases/usecases.js';
+import { NoReposFoundError } from '../lib/errors.js';
+import { resolveWorkspace } from '../lib/workspaceResolver.js';
+import { buildRepoCheckboxChoices } from './helpers.js';
+export async function runAdd(branchName, useCases, services, deps) {
+    // 1. Resolve workspace (from arg or cwd)
+    const { workspacePath, displayName } = resolveWorkspace(branchName, services.workspaceDir, services.config, services.process);
+    const { sourcePath } = services.config.getRequired();
+    const config = services.config.load();
+    // 2. Discover all repos
+    const repos = services.repos.discoverRepos(sourcePath);
+    if (repos.length === 0) {
+        throw new NoReposFoundError(sourcePath);
+    }
+    // 3. Filter out repos already in the workspace
+    const existingWorktrees = services.workspaceDir
+        .getWorktreeDirs(workspacePath)
+        .map((dir) => path.basename(dir));
+    const existingSet = new Set(existingWorktrees);
+    const availableRepos = repos.filter((repoPath) => !existingSet.has(path.basename(repoPath)));
+    if (availableRepos.length === 0) {
+        services.console.log('All repos are already in this workspace.');
+        return;
+    }
+    // 4. Repo picker (same pattern as branch command)
+    const checkboxChoices = buildRepoCheckboxChoices(availableRepos, services, config, (label) => new Separator(label));
+    const selected = await deps.checkbox({
+        message: `Select repos to add to "${displayName}":`,
+        choices: checkboxChoices,
+        pageSize: 20,
+        loop: false,
+    });
+    if (selected.length === 0) {
+        services.console.log('No repos selected.');
+        return;
+    }
+    // 5. Ask for source branch
+    const sourceBranch = await deps.input({
+        message: 'Branch from which branch?',
+        default: 'master',
+    });
+    // 6. Post-checkout confirmation
+    let shouldRunPostCheckout = false;
+    if (config.postCheckout) {
+        shouldRunPostCheckout = await deps.confirm({
+            message: `Run "${config.postCheckout}" in new workspaces?`,
+            default: true,
+        });
+    }
+    services.console.log('\nAdding repos to workspace...');
+    // 7. Fetch selected repos
+    await services.fetch.fetchRepos(selected, {
+        ttlSeconds: config.fetchCacheTtlSeconds,
+    });
+    // 8. For each selected repo in parallel: createBranch then addToWorkspace
+    // If tmux is enabled, use the workspace branch name as session name
+    const sessionName = config.tmux ? displayName : undefined;
+    const results = await Promise.allSettled(selected.map(async (repoPath) => {
+        const repoName = path.basename(repoPath);
+        // Resolve per-repo post-checkout command
+        const repoConf = services.repoConfig.load(repoPath);
+        const resolvedPostCheckout = shouldRunPostCheckout
+            ? services.repoConfig.resolvePostCheckout(repoName, config.perRepoPostCheckout, repoConf, config.postCheckout)
+            : undefined;
+        // a. Create branch in source repo
+        const branchResult = await useCases.createBranch.execute({
+            repoPath,
+            branchName: displayName,
+            sourceBranch,
+        });
+        // b. Add repo to workspace (creates worktree, copies files, tmux pane, post-checkout)
+        return useCases.addToWorkspace.execute({
+            repoPath,
+            workspacePath,
+            branchName: displayName,
+            baseBranch: branchResult.baseBranch,
+            sessionName,
+            copyFiles: config.copyFiles,
+            postCheckout: resolvedPostCheckout,
+        });
+    }));
+    // 9. Track usage
+    services.fetchCache.trackBranchUsage(selected.map((r) => path.basename(r)));
+    // Tally results
+    const successCount = results.filter((r) => r.status === 'fulfilled').length;
+    const totalCount = results.length;
+    const postCheckoutResults = results
+        .filter((r) => r.status === 'fulfilled')
+        .map((r) => r.value)
+        .filter((r) => r.postCheckoutRan);
+    const postCheckoutSuccess = postCheckoutResults.filter((r) => r.postCheckoutSuccess).length;
+    const postCheckoutTotal = postCheckoutResults.length;
+    // 10. Display results
+    services.console.log(`\nAdded ${successCount}/${totalCount} repos to ${chalk.cyan(workspacePath)}.`);
+    if (postCheckoutTotal > 0) {
+        services.console.log(`\nCompleted post-checkout in ${postCheckoutSuccess}/${postCheckoutTotal} workspace(s).`);
+    }
+}
+export function registerAddCommand(program) {
+    program
+        .command('add [branch-name]')
+        .description('Add repos to an existing workspace (auto-detects from current directory if branch not provided)')
+        .action(async (branchName) => {
+        const services = createServices();
+        const useCases = createUseCases(services);
+        try {
+            await runAdd(branchName, useCases, services, { checkbox, input, confirm });
+        }
+        catch (error) {
+            services.console.error(error.message);
+            services.process.exit(1);
+        }
+    });
+}

package/dist/commands/branch.js

@@ -6,6 +6,7 @@ import chalk from 'chalk';
 import { createServices } from '../lib/services.js';
 import { createUseCases } from '../usecases/usecases.js';
 import { NoReposFoundError } from '../lib/errors.js';
+import { buildRepoCheckboxChoices } from './helpers.js';
 export async function runBranch(branchName, useCases, services, deps) {
     const { sourcePath, destPath } = services.config.getRequired();
     const config = services.config.load();
@@ -14,25 +15,7 @@ export async function runBranch(branchName, useCases, services, deps) {
         throw new NoReposFoundError(sourcePath);
     }
     // User prompts
-    const choices = services.repos.formatRepoChoices(repos).map((choice) => ({
-        ...choice,
-        checked: config.branchAutoSelectRepos.includes(choice.name),
-    }));
-    const recentlyUsed = new Set(services.fetchCache.getRecentlyUsedRepos(8));
-    const commonlyUsed = choices.filter((c) => recentlyUsed.has(c.name));
-    let checkboxChoices;
-    if (commonlyUsed.length > 0) {
-        const commonlyUsedNames = new Set(commonlyUsed.map((c) => c.name));
-        const remaining = choices.filter((c) => !commonlyUsedNames.has(c.name));
-        checkboxChoices = [
-            new Separator('Recently Used'),
-            ...commonlyUsed,
-            ...(remaining.length > 0 ? [new Separator(), ...remaining] : []),
-        ];
-    }
-    else {
-        checkboxChoices = choices;
-    }
+    const checkboxChoices = buildRepoCheckboxChoices(repos, services, config, (label) => new Separator(label));
     const selected = await deps.checkbox({
         message: `Select repos for branch "${branchName}":`,
         choices: checkboxChoices,
@@ -59,27 +42,58 @@ export async function runBranch(branchName, useCases, services, deps) {
     await services.fetch.fetchRepos(selected, {
         ttlSeconds: config.fetchCacheTtlSeconds,
     });
-    // Execute use case
-    const result = await useCases.createBranchWorkspace.execute({
-        repos: selected,
+    // 1. Create workspace directory, placeholder config, AGENTS.md, tmux session
+    const workspaceResult = await useCases.createWorkspace.execute({
         branchName,
-        sourceBranch,
         sourcePath,
         destPath,
-        copyFiles: config.copyFiles,
         tmux: config.tmux,
-        postCheckout: shouldRunPostCheckout ? config.postCheckout : undefined,
-        perRepoPostCheckout: shouldRunPostCheckout ? config.perRepoPostCheckout : {},
     });
+    const { workspacePath, tmuxCreated } = workspaceResult;
+    const sessionName = tmuxCreated ? branchName : undefined;
+    // 2. For each selected repo in parallel: createBranch then addToWorkspace
+    const results = await Promise.allSettled(selected.map(async (repoPath) => {
+        const repoName = path.basename(repoPath);
+        // Resolve per-repo post-checkout command
+        const repoConf = services.repoConfig.load(repoPath);
+        const resolvedPostCheckout = shouldRunPostCheckout
+            ? services.repoConfig.resolvePostCheckout(repoName, config.perRepoPostCheckout, repoConf, config.postCheckout)
+            : undefined;
+        // a. Create branch in source repo
+        const branchResult = await useCases.createBranch.execute({
+            repoPath,
+            branchName,
+            sourceBranch,
+        });
+        // b. Add repo to workspace (creates worktree, copies files, tmux pane, post-checkout)
+        return useCases.addToWorkspace.execute({
+            repoPath,
+            workspacePath,
+            branchName,
+            baseBranch: branchResult.baseBranch,
+            sessionName,
+            copyFiles: config.copyFiles,
+            postCheckout: resolvedPostCheckout,
+        });
+    }));
     // Track which repos were branched from
     services.fetchCache.trackBranchUsage(selected.map((r) => path.basename(r)));
+    // Tally results
+    const successCount = results.filter((r) => r.status === 'fulfilled').length;
+    const totalCount = results.length;
+    const postCheckoutResults = results
+        .filter((r) => r.status === 'fulfilled')
+        .map((r) => r.value)
+        .filter((r) => r.postCheckoutRan);
+    const postCheckoutSuccess = postCheckoutResults.filter((r) => r.postCheckoutSuccess).length;
+    const postCheckoutTotal = postCheckoutResults.length;
     // Display results
-    services.console.log(`\nCreated workspace at ${chalk.cyan(result.workspacePath)} with ${result.successCount}/${result.totalCount} repos.`);
-    if (result.tmuxCreated) {
+    services.console.log(`\nCreated workspace at ${chalk.cyan(workspacePath)} with ${successCount}/${totalCount} repos.`);
+    if (tmuxCreated) {
         services.console.log(`Created tmux session: ${chalk.cyan(branchName)}`);
     }
-    if (result.postCheckoutSuccess !== undefined) {
-        services.console.log(`\nCompleted post-checkout in ${result.postCheckoutSuccess}/${result.postCheckoutTotal} workspace(s).`);
+    if (postCheckoutTotal > 0) {
+        services.console.log(`\nCompleted post-checkout in ${postCheckoutSuccess}/${postCheckoutTotal} workspace(s).`);
     }
     else if (!config.postCheckout) {
         services.console.log('\nTip: Configure a post-checkout command to run automatically after branching/checkout.');

package/dist/commands/checkout.js

@@ -1,3 +1,4 @@
+import path from 'node:path';
 import confirm from '@inquirer/confirm';
 import chalk from 'chalk';
 import { createServices } from '../lib/services.js';
@@ -14,23 +15,18 @@ export async function runCheckout(branchName, useCases, services, deps) {
     }
     services.console.log('\nChecking for branch...');
     try {
-        // Fetch all repos from source-path
+        // 1. Fetch all repos from source-path
         await useCases.fetchAllRepos.execute({
             sourcePath,
             fetchCacheTtlSeconds: config.fetchCacheTtlSeconds,
         });
-        // Execute use case
-        const result = await useCases.checkoutWorkspace.execute({
-            branchName,
+        // 2. Discover repos and find which ones have the branch
+        const discoverResult = await useCases.discoverReposWithBranch.execute({
             sourcePath,
-            destPath,
-            copyFiles: config.copyFiles,
-            tmux: config.tmux,
-            postCheckout: shouldRunPostCheckout ? config.postCheckout : undefined,
-            perRepoPostCheckout: shouldRunPostCheckout ? config.perRepoPostCheckout : {},
+            branchName,
         });
-        // Display branch check results
-        for (const checkResult of result.branchCheckResults) {
+        // 3. Display per-repo branch check results
+        for (const checkResult of discoverResult.branchCheckResults) {
             if (checkResult.error) {
                 services.console.log(`${checkResult.repoName}... ${chalk.red(`error: ${checkResult.error}`)}`);
             }
@@ -41,12 +37,56 @@ export async function runCheckout(branchName, useCases, services, deps) {
                 services.console.log(`${checkResult.repoName}... ${chalk.dim('no branch')}`);
             }
         }
-        services.console.log(`\nCreated workspace at ${chalk.cyan(result.workspacePath)} with ${result.successCount}/${result.totalCount} repos.`);
-        if (result.tmuxCreated) {
+        // 4. Throw error if no repos match
+        if (discoverResult.matchingRepos.length === 0) {
+            throw new Error(`Branch "${branchName}" not found in any repo.`);
+        }
+        // 5. Create workspace directory, placeholder config, AGENTS.md, tmux session
+        const workspaceResult = await useCases.createWorkspace.execute({
+            branchName,
+            sourcePath,
+            destPath,
+            tmux: config.tmux,
+        });
+        const { workspacePath, tmuxCreated } = workspaceResult;
+        const sessionName = tmuxCreated ? branchName : undefined;
+        // 6. For each matching repo in parallel: detect base branch, then addToWorkspace
+        const results = await Promise.allSettled(discoverResult.matchingRepos.map(async (repoPath) => {
+            const repoName = path.basename(repoPath);
+            // Resolve per-repo post-checkout command
+            const repoConf = services.repoConfig.load(repoPath);
+            const resolvedPostCheckout = shouldRunPostCheckout
+                ? services.repoConfig.resolvePostCheckout(repoName, config.perRepoPostCheckout, repoConf, config.postCheckout)
+                : undefined;
+            // Detect base branch for this repo
+            const baseBranch = await services.git.findFirstExistingBranch(repoPath, ['master', 'main', 'trunk', 'develop']) ?? 'master';
+            // Add repo to workspace (creates worktree, copies files, tmux pane, post-checkout)
+            return useCases.addToWorkspace.execute({
+                repoPath,
+                workspacePath,
+                branchName,
+                baseBranch,
+                sessionName,
+                copyFiles: config.copyFiles,
+                postCheckout: resolvedPostCheckout,
+            });
+        }));
+        // Tally results
+        const successCount = results.filter((r) => r.status === 'fulfilled').length;
+        const totalCount = results.length;
+        const postCheckoutResults = results
+            .filter((r) => r.status === 'fulfilled')
+            .map((r) => r.value)
+            .filter((r) => r.postCheckoutRan);
+        const postCheckoutSuccess = postCheckoutResults.filter((r) => r.postCheckoutSuccess).length;
+        const postCheckoutTotal = postCheckoutResults.length;
+        // 7. Display results
+        services.console.log(`\nCreated workspace at ${chalk.cyan(workspacePath)} with ${successCount}/${totalCount} repos.`);
+        if (tmuxCreated) {
             services.console.log(`Created tmux session: ${chalk.cyan(branchName)}`);
         }
-        if (result.postCheckoutSuccess !== undefined) {
-            services.console.log(`\nCompleted post-checkout in ${result.postCheckoutSuccess}/${result.postCheckoutTotal} workspace(s).`);
+        if (postCheckoutTotal > 0) {
+            services.console.log(`\nCompleted post-checkout in ${postCheckoutSuccess}/${postCheckoutTotal} workspace(s).`);
         }
         else if (!config.postCheckout) {
             services.console.log('\nTip: Configure a post-checkout command to run automatically after branching/checkout.');

package/dist/commands/helpers.js

@@ -47,6 +47,30 @@ export function logStatus(header, workspaces, linesToClear, getBaseBranch, conso
         console.log('');
     }
 }
+/**
+ * Build the ordered list of checkbox choices for a repo picker, grouping recently used
+ * repos under a "Recently Used" separator and placing the rest below.
+ *
+ * @param createSeparator - factory from the display layer (e.g. inquirer's Separator constructor)
+ */
+export function buildRepoCheckboxChoices(repos, services, config, createSeparator) {
+    const choices = services.repos.formatRepoChoices(repos).map((choice) => ({
+        ...choice,
+        checked: config.branchAutoSelectRepos.includes(choice.name),
+    }));
+    const recentlyUsed = new Set(services.fetchCache.getRecentlyUsedRepos(8));
+    const commonlyUsed = choices.filter((c) => recentlyUsed.has(c.name));
+    if (commonlyUsed.length > 0) {
+        const commonlyUsedNames = new Set(commonlyUsed.map((c) => c.name));
+        const remaining = choices.filter((c) => !commonlyUsedNames.has(c.name));
+        return [
+            createSeparator('Recently Used'),
+            ...commonlyUsed,
+            ...(remaining.length > 0 ? [createSeparator(), ...remaining] : []),
+        ];
+    }
+    return choices;
+}
 /**
  * Get a human-readable status indicator for a workspace based on its worktree statuses.
  */

package/dist/lib/git.js

@@ -127,6 +127,9 @@ export class GitService {
             return true;
         }
     }
+    async createBranch(repoPath, branchName, startPoint) {
+        await this.exec(repoPath, ['branch', '--no-track', branchName, startPoint]);
+    }
     async removeWorktree(repoPath, worktreePath) {
         await this.exec(repoPath, ['worktree', 'remove', worktreePath]);
     }

package/dist/lib/repoConfig.js

@@ -0,0 +1,60 @@
+import path from 'node:path';
+import { z } from 'zod';
+const RepoConfigSchema = z.object({
+    'copy-files': z.string().optional(),
+    'post-checkout': z.string().optional(),
+});
+/**
+ * RepoConfigService handles loading per-repo flow-config.json files
+ * from source repositories.
+ */
+export class RepoConfigService {
+    fs;
+    constructor(fs) {
+        this.fs = fs;
+    }
+    /**
+     * Load flow-config.json from a repo's root directory.
+     * Returns undefined if the file doesn't exist, is invalid JSON, or has no relevant fields.
+     */
+    load(repoPath) {
+        const configPath = path.join(repoPath, 'flow-config.json');
+        if (!this.fs.existsSync(configPath)) {
+            return undefined;
+        }
+        try {
+            const raw = this.fs.readFileSync(configPath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            const validated = RepoConfigSchema.parse(parsed);
+            const copyFiles = validated['copy-files'];
+            const postCheckout = validated['post-checkout'];
+            // Return undefined if no relevant fields are set
+            if (!copyFiles && !postCheckout) {
+                return undefined;
+            }
+            return { copyFiles, postCheckout };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Resolve the post-checkout command for a repo with 3-level precedence:
+     * 1. per-repo-post-checkout from central config (highest priority)
+     * 2. post-checkout from repo's flow-config.json
+     * 3. global post-checkout from central config (lowest priority)
+     */
+    resolvePostCheckout(repoName, perRepoPostCheckout, repoConfig, globalPostCheckout) {
+        return (perRepoPostCheckout?.[repoName] ??
+            repoConfig?.postCheckout ??
+            globalPostCheckout);
+    }
+    /**
+     * Resolve the copy-files for a repo with 2-level precedence:
+     * 1. copy-files from repo's flow-config.json (overrides global)
+     * 2. global copy-files from central config
+     */
+    resolveCopyFiles(repoConfig, globalCopyFiles) {
+        return repoConfig?.copyFiles ?? globalCopyFiles;
+    }
+}

package/dist/lib/services.js

@@ -14,6 +14,7 @@ import { FetchCacheService } from './fetchCache.js';
 import { ParallelService } from './parallel.js';
 import { StatusService } from './status.js';
 import { TmuxService } from './tmux.js';
+import { RepoConfigService } from './repoConfig.js';
 export function createServices() {
     // Create adapters
     const fs = new NodeFileSystem();
@@ -30,6 +31,7 @@ export function createServices() {
     const fetch = new FetchService(git, console, fetchCache);
     const repos = new RepoService(fs, git);
     const postCheckout = new PostCheckoutService(shell);
+    const repoConfig = new RepoConfigService(fs);
     // Focused workspace services
     const workspaceDir = new WorkspaceDirectoryService(fs);
     const workspaceConfig = new WorkspaceConfigService(fs);
@@ -42,6 +44,7 @@ export function createServices() {
         workspaceConfig,
         worktree,
         postCheckout,
+        repoConfig,
         fetch,
         fetchCache,
         parallel,

package/dist/lib/tmux.js

@@ -53,6 +53,29 @@ export class TmuxService {
             'Enter',
         ]);
     }
+    async addPane(sessionName, worktreePath) {
+        await this.shell.execFile('tmux', [
+            'split-window',
+            '-t',
+            sessionName,
+            '-c',
+            worktreePath,
+        ]);
+        const { stdout } = await this.shell.execFile('tmux', [
+            'display-message',
+            '-p',
+            '-t',
+            sessionName,
+            '#{pane_index}',
+        ]);
+        await this.shell.execFile('tmux', [
+            'select-layout',
+            '-t',
+            sessionName,
+            'tiled',
+        ]);
+        return parseInt(stdout.trim(), 10);
+    }
     async killSession(sessionName) {
         try {
             await this.shell.execFile('tmux', ['kill-session', '-t', sessionName]);

package/dist/usecases/addToWorkspace.js

@@ -0,0 +1,75 @@
+import path from 'node:path';
+/**
+ * Use case for adding a single repo to an existing workspace.
+ * Creates a worktree for an existing branch, copies config files,
+ * saves base branch to workspace config, adds a tmux pane (if enabled),
+ * and runs post-checkout (if configured).
+ */
+export class AddToWorkspaceUseCase {
+    worktree;
+    workspaceConfig;
+    repoConfig;
+    postCheckout;
+    tmux;
+    constructor(worktree, workspaceConfig, repoConfig, postCheckout, tmux) {
+        this.worktree = worktree;
+        this.workspaceConfig = workspaceConfig;
+        this.repoConfig = repoConfig;
+        this.postCheckout = postCheckout;
+        this.tmux = tmux;
+    }
+    async execute(params) {
+        const repoName = path.basename(params.repoPath);
+        const worktreeDest = path.join(params.workspacePath, repoName);
+        // 1. Create worktree by checking out the existing branch
+        await this.worktree.createWorktreeCheckout(params.repoPath, worktreeDest, params.branchName);
+        // 2. Resolve and copy config files using repo-level overrides with global fallback
+        const repoConf = this.repoConfig.load(params.repoPath);
+        const resolvedCopyFiles = this.repoConfig.resolveCopyFiles(repoConf, params.copyFiles);
+        this.worktree.copyConfigFilesToWorktree(params.repoPath, worktreeDest, resolvedCopyFiles);
+        // 3. Save base branch to workspace config
+        this.workspaceConfig.save(params.workspacePath, {
+            baseBranches: { [repoName]: params.baseBranch },
+        });
+        // 4. Add tmux pane (if session name provided)
+        let paneIndex;
+        let tmuxPaneAdded = false;
+        if (params.sessionName) {
+            try {
+                paneIndex = await this.tmux.addPane(params.sessionName, worktreeDest);
+                tmuxPaneAdded = true;
+            }
+            catch {
+                // Don't fail if tmux pane addition fails
+            }
+        }
+        // 5. Run post-checkout command (if configured)
+        const postCheckoutCommand = params.postCheckout;
+        let postCheckoutRan = false;
+        let postCheckoutSuccess = false;
+        if (postCheckoutCommand) {
+            postCheckoutRan = true;
+            try {
+                if (params.sessionName !== undefined && paneIndex !== undefined) {
+                    // tmux enabled: send keys to the pane
+                    await this.tmux.sendKeysToPane(params.sessionName, paneIndex, postCheckoutCommand);
+                }
+                else {
+                    // tmux disabled: run command directly in worktree directory
+                    await this.postCheckout.runCommandInDirectory(worktreeDest, postCheckoutCommand);
+                }
+                postCheckoutSuccess = true;
+            }
+            catch {
+                // Post-checkout failure is non-fatal; reported via postCheckoutSuccess: false
+            }
+        }
+        return {
+            repoName,
+            worktreePath: worktreeDest,
+            postCheckoutRan,
+            postCheckoutSuccess,
+            tmuxPaneAdded,
+        };
+    }
+}

package/dist/usecases/createBranch.js

@@ -0,0 +1,33 @@
+import { RepoService } from '../lib/repos.js';
+const DEFAULT_BRANCH_CANDIDATES = ['master', 'main', 'trunk', 'develop'];
+/**
+ * Use case for creating a git branch in a single repo.
+ * Handles fallback to default branches when the source branch doesn't exist.
+ */
+export class CreateBranchUseCase {
+    git;
+    constructor(git) {
+        this.git = git;
+    }
+    async execute(params) {
+        const repoName = RepoService.getRepoName(params.repoPath);
+        // 1. Check if the source branch exists as a remote-tracking branch
+        const sourceBranchExists = await this.git.localRemoteBranchExists(params.repoPath, params.sourceBranch);
+        let actualBaseBranch = params.sourceBranch;
+        // 2. Fall back to first existing default branch if source branch doesn't exist
+        if (!sourceBranchExists) {
+            const fallback = await this.git.findFirstExistingBranch(params.repoPath, DEFAULT_BRANCH_CANDIDATES);
+            if (fallback === null) {
+                throw new Error(`Cannot create branch in ${repoName}: source branch "${params.sourceBranch}" not found and no fallback branch exists (tried: ${DEFAULT_BRANCH_CANDIDATES.join(', ')})`);
+            }
+            actualBaseBranch = fallback;
+        }
+        // 3. Create the branch from origin/<actualBaseBranch>
+        await this.git.createBranch(params.repoPath, params.branchName, `origin/${actualBaseBranch}`);
+        // 4. Return the actual base branch used
+        return {
+            repoName,
+            baseBranch: actualBaseBranch,
+        };
+    }
+}

package/dist/usecases/createWorkspace.js

@@ -0,0 +1,37 @@
+/**
+ * Use case for creating a new workspace directory with initial config, AGENTS.md copy,
+ * and an optional tmux session (root pane only, no worktrees yet).
+ */
+export class CreateWorkspaceUseCase {
+    workspaceDir;
+    workspaceConfig;
+    tmux;
+    constructor(workspaceDir, workspaceConfig, tmux) {
+        this.workspaceDir = workspaceDir;
+        this.workspaceConfig = workspaceConfig;
+        this.tmux = tmux;
+    }
+    async execute(params) {
+        // 1. Create workspace directory
+        const workspacePath = this.workspaceDir.createWorkspaceDir(params.destPath, params.branchName);
+        // 2. Save placeholder config
+        this.workspaceConfig.savePlaceholder(workspacePath);
+        // 3. Copy AGENTS.md if it exists in source-path
+        this.workspaceDir.copyAgentsMd(params.sourcePath, workspacePath);
+        // 4. Create tmux session (root pane only) if enabled
+        let tmuxCreated = false;
+        if (params.tmux) {
+            try {
+                await this.tmux.createSession(workspacePath, params.branchName, []);
+                tmuxCreated = true;
+            }
+            catch {
+                // Don't fail the workspace creation, just report tmux wasn't created
+            }
+        }
+        return {
+            workspacePath,
+            tmuxCreated,
+        };
+    }
+}

package/dist/usecases/discoverReposWithBranch.js

@@ -0,0 +1,25 @@
+import { NoReposFoundError } from '../lib/errors.js';
+/**
+ * Use case for discovering repos in source-path and checking which ones have a given branch.
+ * Extracts repo discovery + branch checking logic into a focused, reusable use case.
+ */
+export class DiscoverReposWithBranchUseCase {
+    repos;
+    constructor(repos) {
+        this.repos = repos;
+    }
+    async execute(params) {
+        // 1. Discover all repos
+        const allRepos = this.repos.discoverRepos(params.sourcePath);
+        if (allRepos.length === 0) {
+            throw new NoReposFoundError(params.sourcePath);
+        }
+        // 2. Check which repos have the branch
+        const { matching, results } = await this.repos.findReposWithBranch(allRepos, params.branchName);
+        return {
+            allRepos,
+            matchingRepos: matching,
+            branchCheckResults: results,
+        };
+    }
+}

package/dist/usecases/usecases.js

@@ -1,5 +1,3 @@
-import { CreateBranchWorkspaceUseCase } from './createBranchWorkspace.js';
-import { CheckoutWorkspaceUseCase } from './checkoutWorkspace.js';
 import { RemoveWorkspaceUseCase } from './removeWorkspace.js';
 import { PushWorkspaceUseCase } from './pushWorkspace.js';
 import { PullWorkspaceUseCase } from './pullWorkspace.js';
@@ -10,20 +8,19 @@ import { FetchAllReposUseCase } from './fetchAllRepos.js';
 import { FetchWorkspaceReposUseCase } from './fetchWorkspaceRepos.js';
 import { FetchUsedReposUseCase } from './fetchUsedRepos.js';
 import { ResumeTmuxSessionsUseCase } from './resumeTmuxSessions.js';
-import { RunPostCheckoutUseCase } from './runPostCheckout.js';
+import { CreateWorkspaceUseCase } from './createWorkspace.js';
+import { CreateBranchUseCase } from './createBranch.js';
+import { AddToWorkspaceUseCase } from './addToWorkspace.js';
+import { DiscoverReposWithBranchUseCase } from './discoverReposWithBranch.js';
 /**
  * Factory function for creating all use cases with their service dependencies.
  * Use cases orchestrate workflows by coordinating multiple services.
  */
 export function createUseCases(services) {
-    // Create use cases that are dependencies first
-    const runPostCheckout = new RunPostCheckoutUseCase(services.workspaceDir, services.postCheckout, services.tmux);
     return {
         fetchAllRepos: new FetchAllReposUseCase(services.fetch, services.repos),
         fetchWorkspaceRepos: new FetchWorkspaceReposUseCase(services.workspaceDir, services.fetch),
         fetchUsedRepos: new FetchUsedReposUseCase(services.workspaceDir, services.fetch),
-        createBranchWorkspace: new CreateBranchWorkspaceUseCase(services.workspaceDir, services.workspaceConfig, services.worktree, services.repos, services.git, services.parallel, services.tmux, runPostCheckout),
-        checkoutWorkspace: new CheckoutWorkspaceUseCase(services.workspaceDir, services.workspaceConfig, services.worktree, services.repos, services.git, services.parallel, services.tmux, runPostCheckout),
         removeWorkspace: new RemoveWorkspaceUseCase(services.workspaceDir, services.workspaceConfig, services.worktree, services.repos, services.status, services.tmux),
         pushWorkspace: new PushWorkspaceUseCase(services.workspaceDir, services.git, services.parallel),
         pullWorkspace: new PullWorkspaceUseCase(services.workspaceDir, services.git, services.parallel),
@@ -31,6 +28,9 @@ export function createUseCases(services) {
         discoverPrunableWorkspaces: new DiscoverPrunableWorkspacesUseCase(services.workspaceDir, services.workspaceConfig, services.status, services.git),
         listWorkspacesWithStatus: new ListWorkspacesWithStatusUseCase(services.workspaceDir, services.workspaceConfig, services.status),
         resumeTmuxSessions: new ResumeTmuxSessionsUseCase(services.workspaceDir, services.tmux),
-        runPostCheckout,
+        createWorkspace: new CreateWorkspaceUseCase(services.workspaceDir, services.workspaceConfig, services.tmux),
+        createBranch: new CreateBranchUseCase(services.git),
+        addToWorkspace: new AddToWorkspaceUseCase(services.worktree, services.workspaceConfig, services.repoConfig, services.postCheckout, services.tmux),
+        discoverReposWithBranch: new DiscoverReposWithBranchUseCase(services.repos),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worktree-flow",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "description": "Manage git worktrees across a poly-repo environment",
   "type": "module",
   "bin": {

package/dist/usecases/checkoutWorkspace.js

@@ -1,91 +0,0 @@
-import path from 'node:path';
-import { RepoService } from '../lib/repos.js';
-import { NoReposFoundError } from '../lib/errors.js';
-/**
- * Use case for checking out an existing branch across multiple repos.
- * Orchestrates repo discovery, branch checking, and workspace creation.
- */
-export class CheckoutWorkspaceUseCase {
-    workspaceDir;
-    workspaceConfig;
-    worktree;
-    repos;
-    git;
-    parallel;
-    tmux;
-    runPostCheckout;
-    constructor(workspaceDir, workspaceConfig, worktree, repos, git, parallel, tmux, runPostCheckout) {
-        this.workspaceDir = workspaceDir;
-        this.workspaceConfig = workspaceConfig;
-        this.worktree = worktree;
-        this.repos = repos;
-        this.git = git;
-        this.parallel = parallel;
-        this.tmux = tmux;
-        this.runPostCheckout = runPostCheckout;
-    }
-    async execute(params) {
-        // 1. Discover all repos
-        const allRepos = this.repos.discoverRepos(params.sourcePath);
-        if (allRepos.length === 0) {
-            throw new NoReposFoundError(params.sourcePath);
-        }
-        // 2. Find repos that have this branch
-        const { matching, results } = await this.repos.findReposWithBranch(allRepos, params.branchName);
-        if (matching.length === 0) {
-            throw new Error(`Branch "${params.branchName}" not found in any repo.`);
-        }
-        // 3. Create workspace directory
-        const workspacePath = this.workspaceDir.createWorkspaceDir(params.destPath, params.branchName);
-        this.workspaceConfig.savePlaceholder(workspacePath);
-        // 4. Create worktrees in parallel
-        const successCount = await this.parallel.processInParallel(matching, (repoPath) => RepoService.getRepoName(repoPath), async (repoPath) => {
-            const name = RepoService.getRepoName(repoPath);
-            const worktreeDest = path.join(workspacePath, name);
-            await this.worktree.createWorktreeCheckout(repoPath, worktreeDest, params.branchName);
-            this.worktree.copyConfigFilesToWorktree(repoPath, worktreeDest, params.copyFiles);
-            return 'created';
-        });
-        // 5. Copy AGENTS.md
-        this.workspaceDir.copyAgentsMd(params.sourcePath, workspacePath);
-        // 6. Detect base branches for each repo
-        const baseBranches = {};
-        for (const repoPath of matching) {
-            const repoName = RepoService.getRepoName(repoPath);
-            const baseBranch = await this.git.findFirstExistingBranch(repoPath, ['master', 'main', 'trunk', 'develop']);
-            baseBranches[repoName] = baseBranch || 'master';
-        }
-        // 7. Save workspace config with base branches
-        this.workspaceConfig.save(workspacePath, { baseBranches });
-        // 8. Create tmux session if enabled
-        let tmuxCreated = false;
-        if (params.tmux) {
-            try {
-                const worktreeDirs = this.workspaceDir.getWorktreeDirs(workspacePath);
-                await this.tmux.createSession(workspacePath, params.branchName, worktreeDirs);
-                tmuxCreated = true;
-            }
-            catch (error) {
-                // Don't fail
-            }
-        }
-        // 9. Run post-checkout if configured
-        const postCheckoutResult = await this.runPostCheckout.execute({
-            workspacePath,
-            sessionName: tmuxCreated ? params.branchName : undefined,
-            tmuxEnabled: tmuxCreated,
-            postCheckout: params.postCheckout,
-            perRepoPostCheckout: params.perRepoPostCheckout,
-        });
-        return {
-            workspacePath,
-            matchingRepos: matching.length,
-            successCount,
-            totalCount: matching.length,
-            tmuxCreated,
-            postCheckoutSuccess: postCheckoutResult?.successCount,
-            postCheckoutTotal: postCheckoutResult?.totalCount,
-            branchCheckResults: results,
-        };
-    }
-}

package/dist/usecases/createBranchWorkspace.js

@@ -1,86 +0,0 @@
-import path from 'node:path';
-import { RepoService } from '../lib/repos.js';
-/**
- * Use case for creating a workspace with new branches across multiple repos.
- * Orchestrates the entire workflow from workspace creation to post-checkout commands.
- */
-export class CreateBranchWorkspaceUseCase {
-    workspaceDir;
-    workspaceConfig;
-    worktree;
-    repos;
-    git;
-    parallel;
-    tmux;
-    runPostCheckout;
-    constructor(workspaceDir, workspaceConfig, worktree, repos, git, parallel, tmux, runPostCheckout) {
-        this.workspaceDir = workspaceDir;
-        this.workspaceConfig = workspaceConfig;
-        this.worktree = worktree;
-        this.repos = repos;
-        this.git = git;
-        this.parallel = parallel;
-        this.tmux = tmux;
-        this.runPostCheckout = runPostCheckout;
-    }
-    async execute(params) {
-        // 1. Create workspace directory
-        const workspacePath = this.workspaceDir.createWorkspaceDir(params.destPath, params.branchName);
-        this.workspaceConfig.savePlaceholder(workspacePath);
-        // Track base branches for each repo
-        const baseBranches = {};
-        // 2. Create worktrees in parallel
-        const successCount = await this.parallel.processInParallel(params.repos, (repoPath) => RepoService.getRepoName(repoPath), async (repoPath) => {
-            const name = RepoService.getRepoName(repoPath);
-            const worktreeDest = path.join(workspacePath, name);
-            // Determine which base branch to use
-            let actualBaseBranch = params.sourceBranch;
-            // Try the user-specified source branch first, fall back if it doesn't exist
-            const branchExists = await this.git.localRemoteBranchExists(repoPath, params.sourceBranch);
-            if (!branchExists) {
-                const fallbackBranch = await this.git.findFirstExistingBranch(repoPath, ['master', 'main', 'trunk', 'develop']);
-                if (fallbackBranch) {
-                    actualBaseBranch = fallbackBranch;
-                }
-                // If no fallback found, still try with the original (will fail with clear error)
-            }
-            // Track the actual base branch used
-            baseBranches[name] = actualBaseBranch;
-            await this.worktree.createWorktreeWithBranch(repoPath, worktreeDest, params.branchName, `origin/${actualBaseBranch}`);
-            this.worktree.copyConfigFilesToWorktree(repoPath, worktreeDest, params.copyFiles);
-            return 'created';
-        });
-        // 3. Copy AGENTS.md if exists
-        this.workspaceDir.copyAgentsMd(params.sourcePath, workspacePath);
-        // 4. Save workspace config with base branches
-        this.workspaceConfig.save(workspacePath, { baseBranches });
-        // 5. Create tmux session if enabled
-        let tmuxCreated = false;
-        if (params.tmux) {
-            try {
-                const worktreeDirs = this.workspaceDir.getWorktreeDirs(workspacePath);
-                await this.tmux.createSession(workspacePath, params.branchName, worktreeDirs);
-                tmuxCreated = true;
-            }
-            catch (error) {
-                // Don't fail, just return false
-            }
-        }
-        // 6. Run post-checkout command if configured
-        const postCheckoutResult = await this.runPostCheckout.execute({
-            workspacePath,
-            sessionName: tmuxCreated ? params.branchName : undefined,
-            tmuxEnabled: tmuxCreated,
-            postCheckout: params.postCheckout,
-            perRepoPostCheckout: params.perRepoPostCheckout,
-        });
-        return {
-            workspacePath,
-            successCount,
-            totalCount: params.repos.length,
-            tmuxCreated,
-            postCheckoutSuccess: postCheckoutResult?.successCount,
-            postCheckoutTotal: postCheckoutResult?.totalCount,
-        };
-    }
-}

package/dist/usecases/runPostCheckout.js

@@ -1,49 +0,0 @@
-import path from 'node:path';
-/**
- * Use case for running post-checkout commands.
- * Runs commands either directly in worktree directories or in tmux panes.
- */
-export class RunPostCheckoutUseCase {
-    workspaceDir;
-    postCheckout;
-    tmux;
-    constructor(workspaceDir, postCheckout, tmux) {
-        this.workspaceDir = workspaceDir;
-        this.postCheckout = postCheckout;
-        this.tmux = tmux;
-    }
-    async execute(params) {
-        // Skip if no commands configured
-        if (!params.postCheckout && (!params.perRepoPostCheckout || Object.keys(params.perRepoPostCheckout).length === 0)) {
-            return undefined;
-        }
-        // Get worktree directories
-        const worktreeDirs = this.workspaceDir.getWorktreeDirs(params.workspacePath);
-        // Map each worktree to its command (per-repo overrides global)
-        const commandsToRun = worktreeDirs
-            .map((dir, index) => {
-            const repoName = path.basename(dir);
-            const command = params.perRepoPostCheckout?.[repoName] ?? params.postCheckout;
-            return command ? { dir, command, paneIndex: index + 1 } : null;
-        })
-            .filter((x) => x !== null);
-        // Run commands in parallel
-        let successCount = 0;
-        await Promise.allSettled(commandsToRun.map(async ({ dir, command, paneIndex }) => {
-            try {
-                if (params.tmuxEnabled && params.sessionName) {
-                    // Panes are indexed from 0, first pane (root) is 0, worktrees start at 1
-                    await this.tmux.sendKeysToPane(params.sessionName, paneIndex, command);
-                }
-                else {
-                    await this.postCheckout.runCommandInDirectory(dir, command);
-                }
-                successCount++;
-            }
-            catch {
-                // Error handled by counting successes
-            }
-        }));
-        return { successCount, totalCount: commandsToRun.length };
-    }
-}