steerdev 1.0.59__tar.gz → 1.0.60__tar.gz

{steerdev-1.0.59 → steerdev-1.0.60}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steerdev
-Version: 1.0.59
+Version: 1.0.60
 Summary: Backend task runner for steerdev.com - orchestrates CLI coding agents with activity reporting
 Project-URL: Homepage, https://github.com/pentoai/steerdev-agent
 Project-URL: Repository, https://github.com/pentoai/steerdev-agent

{steerdev-1.0.59 → steerdev-1.0.60}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "steerdev"
-version = "1.0.59"
+version = "1.0.60"
 description = "Backend task runner for steerdev.com - orchestrates CLI coding agents with activity reporting"
 readme = "README.md"
 authors = [

{steerdev-1.0.59 → steerdev-1.0.60}/src/steerdev_agent/agent_loop.py

@@ -36,6 +36,7 @@ from steerdev_agent.api.sessions import SessionCreateRequest, SessionsClient
 from steerdev_agent.api.tasks import TasksClient
 from steerdev_agent.config.models import (
     AgentLoopConfig,
+    BranchConfig,
     EvidenceConfig,
     ExecutorConfig,
     RetryConfig,
@@ -77,6 +78,7 @@ class CommandExecutor:
     _workflow_id: str | None
     _enable_waves: bool
     _enable_canals: bool
+    _branch_config: BranchConfig
     _worktree_config: WorktreeConfig
     _evidence_config: EvidenceConfig
     _agent_loop_config: AgentLoopConfig
@@ -181,6 +183,7 @@ class CommandExecutor:
             evidence_config=self._evidence_config,
             executor_config=self._executor_config,
             force_workflow_id=None,
+            branch_config=self._branch_config,
             shutdown_event=self._shutdown_event,
             agent_id=self._agent_id,
         )
@@ -498,6 +501,7 @@ class AgentLoop(CommandExecutor):
         worktree_config: WorktreeConfig | None = None,
         evidence_config: EvidenceConfig | None = None,
         retry_config: RetryConfig | None = None,
+        branch_config: BranchConfig | None = None,
     ) -> None:
         self.project_id = project_id
         self.agent_name = agent_name
@@ -509,6 +513,7 @@ class AgentLoop(CommandExecutor):
         self._agent_loop_config = agent_loop_config or AgentLoopConfig()
         self._executor_config = executor_config or ExecutorConfig()
         self._retry_config = retry_config or RetryConfig()
+        self._branch_config = branch_config or BranchConfig()
         self._workflow_id = force_workflow_id
         self._enable_waves = enable_waves
         self._enable_canals = enable_canals
@@ -865,6 +870,7 @@ class WorkspaceAgentLoop(CommandExecutor):
         worktree_config: WorktreeConfig | None = None,
         evidence_config: EvidenceConfig | None = None,
         retry_config: RetryConfig | None = None,
+        branch_config: BranchConfig | None = None,
     ) -> None:
         self.workspace_path = Path(workspace_path)
         self.agent_name = agent_name
@@ -875,6 +881,7 @@ class WorkspaceAgentLoop(CommandExecutor):
         self._agent_loop_config = agent_loop_config or AgentLoopConfig()
         self._executor_config = executor_config or ExecutorConfig()
         self._retry_config = retry_config or RetryConfig()
+        self._branch_config = branch_config or BranchConfig()
         self._workspace_config = workspace_config or WorkspaceConfig()
         self._workflow_id = force_workflow_id
         self._enable_waves = enable_waves
@@ -1287,6 +1294,7 @@ async def run_agent_loop(
     worktree_config: WorktreeConfig | None = None,
     evidence_config: EvidenceConfig | None = None,
     retry_config: RetryConfig | None = None,
+    branch_config: BranchConfig | None = None,
 ) -> None:
     """Run the project-scoped agent loop.
 
@@ -1308,6 +1316,7 @@ async def run_agent_loop(
         worktree_config=worktree_config,
         evidence_config=evidence_config,
         retry_config=retry_config,
+        branch_config=branch_config,
     )
     await agent.start()
 
@@ -1328,6 +1337,7 @@ async def run_workspace_agent_loop(
     worktree_config: WorktreeConfig | None = None,
     evidence_config: EvidenceConfig | None = None,
     retry_config: RetryConfig | None = None,
+    branch_config: BranchConfig | None = None,
 ) -> None:
     """Run the workspace (multi-project) agent loop.
 
@@ -1349,5 +1359,6 @@ async def run_workspace_agent_loop(
         worktree_config=worktree_config,
         evidence_config=evidence_config,
         retry_config=retry_config,
+        branch_config=branch_config,
     )
     await agent.start()

{steerdev-1.0.59 → steerdev-1.0.60}/src/steerdev_agent/cli.py

@@ -1719,6 +1719,13 @@ def run(
             help="Delay between retries in seconds (default: from config or 3600)",
         ),
     ] = None,
+    default_branch: Annotated[
+        str | None,
+        typer.Option(
+            "--default-branch",
+            help="Default branch for sync/rebase/PR targets (default: from config or 'main')",
+        ),
+    ] = None,
 ) -> None:
     """Run the agent for a project!
 
@@ -1820,6 +1827,11 @@ def run(
     if retry_delay is not None:
         retry_config.delay_seconds = retry_delay
 
+    # Resolve branch config: CLI > config > default
+    resolved_branch_config = config.branches.model_copy()
+    if default_branch is not None:
+        resolved_branch_config.default_branch = default_branch
+
     try:
         result = asyncio.run(
             run_agent(
@@ -1838,6 +1850,7 @@ def run(
                 force_workflow_id=resolved_workflow_id,
                 dry_run=dry_run,
                 retry_config=retry_config,
+                branch_config=resolved_branch_config,
             )
         )
 
@@ -1998,6 +2011,13 @@ def agent(
             help="Submit evidence reports after task completion (default: from config or enabled)",
         ),
     ] = None,
+    default_branch: Annotated[
+        str | None,
+        typer.Option(
+            "--default-branch",
+            help="Default branch for sync/rebase/PR targets (default: from config or 'main')",
+        ),
+    ] = None,
 ) -> None:
     """Run the agent in persistent mode.
 
@@ -2075,6 +2095,11 @@ def agent(
     if retry_delay is not None:
         retry_config.delay_seconds = retry_delay
 
+    # Resolve branch config: CLI > config > default
+    resolved_branch_config = config.branches.model_copy()
+    if default_branch is not None:
+        resolved_branch_config.default_branch = default_branch
+
     # Resolve workspace path: CLI > config
     resolved_workspace = workspace or config.workspace.workspace_dir
 
@@ -2099,6 +2124,7 @@ def agent(
                     worktree_config=resolved_worktree_config,
                     evidence_config=resolved_evidence_config,
                     retry_config=retry_config,
+                    branch_config=resolved_branch_config,
                 )
             )
         except KeyboardInterrupt:
@@ -2140,6 +2166,7 @@ def agent(
                     worktree_config=resolved_worktree_config,
                     evidence_config=resolved_evidence_config,
                     retry_config=retry_config,
+                    branch_config=resolved_branch_config,
                 )
             )
         except KeyboardInterrupt:

{steerdev-1.0.59 → steerdev-1.0.60}/src/steerdev_agent/config/models.py

@@ -246,6 +246,22 @@ class CanalConfig(BaseModel):
     ]
 
 
+class BranchConfig(BaseModel):
+    """Branch configuration for git operations.
+
+    Controls which branch is used for pre-flight sync, rebase targets, and PR base.
+    Users set default_branch to whatever their project uses — main, dev, develop, etc.
+    """
+
+    default_branch: Annotated[
+        str,
+        Field(
+            default="main",
+            description="Default branch for sync, rebase, and PR targets (e.g. main, dev, develop)",
+        ),
+    ]
+
+
 class EvidenceConfig(BaseModel):
     """Evidence report configuration.
 
@@ -341,6 +357,10 @@ class SteerDevConfig(BaseModel):
         CanalConfig,
         Field(default_factory=CanalConfig, description="Canal workflow configuration"),
     ]
+    branches: Annotated[
+        BranchConfig,
+        Field(default_factory=BranchConfig, description="Branch configuration for git operations"),
+    ]
     workspace: Annotated[
         WorkspaceConfig,
         Field(default_factory=WorkspaceConfig, description="Workspace agent configuration"),

{steerdev-1.0.59 → steerdev-1.0.60}/src/steerdev_agent/prompt/builder.py

@@ -68,6 +68,10 @@ class PromptContext(BaseModel):
     resume_message: str | None = Field(
         default=None, description="Message for resume (if resuming session)"
     )
+    default_branch: str | None = Field(
+        default=None,
+        description="Default branch for git operations (e.g. main, dev). Falls back to 'main'.",
+    )
 
 
 class PromptBuilder:
@@ -105,7 +109,7 @@ class PromptBuilder:
 
         # Build components
         project_info = self._build_project_info(context.project)
-        task_info = self._build_task_info(context.task, context.project)
+        task_info = self._build_task_info(context.task, context.project, context.default_branch)
         instructions = self._build_instructions(context)
 
         # Add workflow phase if present
@@ -157,12 +161,14 @@ class PromptBuilder:
         self,
         task: TaskContext | None,
         project: ProjectContext | None,
+        default_branch: str | None = None,
     ) -> str:
         """Build task information section.
 
         Args:
             task: Task context or None.
             project: Project context for working directory fallback.
+            default_branch: Default branch for git operations (falls back to "main").
 
         Returns:
             Formatted task information.
@@ -204,8 +210,14 @@ class PromptBuilder:
                 wave_section += f"\n\n**Tasks in This Wave:**\n{task.wave.wave_tasks_summary}"
             task_info = f"{task_info}{wave_section}"
 
-        # Add git pre-flight sync instructions for new tasks (not resumed sessions)
-        task_info = f"{task_info}\n\n{self.templates.GIT_PREFLIGHT_SYNC}"
+        # Add git branch configuration and pre-flight sync instructions
+        branch = default_branch or "main"
+        task_info = (
+            f"{task_info}\n\n{self.templates.GIT_BRANCH_CONFIG.format(default_branch=branch)}"
+        )
+        task_info = (
+            f"{task_info}\n{self.templates.GIT_PREFLIGHT_SYNC.format(default_branch=branch)}"
+        )
 
         return task_info
 

{steerdev-1.0.59 → steerdev-1.0.60}/src/steerdev_agent/prompt/templates.py

@@ -246,13 +246,20 @@ Create tasks that can be completed by a single developer in a reasonable time (1
 Larger work should be broken into multiple tasks.
 """
 
-    # Git pre-flight sync instructions injected into task prompts
+    # Git pre-flight sync instructions injected into task prompts.
+    # Parameterized with {default_branch} — call .format(default_branch=...) before use.
     GIT_PREFLIGHT_SYNC = """## Git Pre-flight Sync
 Before starting this task, ensure you are on an up-to-date default branch:
 1. `git stash push -m "steerdev-preflight" 2>/dev/null || true`
-2. `git checkout main && git pull origin main --ff-only`
-3. If ff-only fails: `git fetch origin && git reset --hard origin/main`
+2. `git checkout {default_branch} && git pull origin {default_branch} --ff-only`
+3. If ff-only fails: `git fetch origin && git reset --hard origin/{default_branch}`
 Only skip this if you are continuing mid-wave on an existing wave branch.
+"""
+
+    # Git branch configuration note injected into task prompts
+    GIT_BRANCH_CONFIG = """## Git Branch Configuration
+- Default branch: `{default_branch}`
+Use this branch for all fetch, rebase, and merge operations.
 """
 
     # Phase context instructions appended to phase prompts

{steerdev-1.0.59 → steerdev-1.0.60}/src/steerdev_agent/runner.py

@@ -19,7 +19,13 @@ from steerdev_agent.api.events import EventsClient
 from steerdev_agent.api.runs import RunCreateRequest, RunsClient
 from steerdev_agent.api.sessions import SessionCreateRequest, SessionsClient
 from steerdev_agent.api.tasks import TasksClient
-from steerdev_agent.config.models import EvidenceConfig, ExecutorConfig, RetryConfig, WorktreeConfig
+from steerdev_agent.config.models import (
+    BranchConfig,
+    EvidenceConfig,
+    ExecutorConfig,
+    RetryConfig,
+    WorktreeConfig,
+)
 from steerdev_agent.executor import ExecutorFactory
 from steerdev_agent.executor.base import AgentExecutor, EventType, StreamEvent
 from steerdev_agent.executor.claude import ClaudeExecutorError
@@ -277,6 +283,7 @@ class Runner:
         force_workflow_id: str | None = None,
         dry_run: bool = False,
         retry_config: RetryConfig | None = None,
+        branch_config: BranchConfig | None = None,
         shutdown_event: asyncio.Event | None = None,
         agent_id: str | None = None,
     ) -> None:
@@ -314,6 +321,7 @@ class Runner:
         self.workflow_id = force_workflow_id
         self.dry_run = dry_run
         self._retry_config = retry_config or RetryConfig()
+        self._branch_config = branch_config or BranchConfig()
         self._shutdown_event = shutdown_event
 
         # Executor configuration
@@ -723,6 +731,7 @@ class Runner:
                 linear_identifier=task.get("linear_identifier"),
                 wave=wave_context,
             ),
+            default_branch=self._branch_config.default_branch,
         )
         prompt = self._prompt_builder.build(context)
 
@@ -753,25 +762,45 @@ class Runner:
         if self._sessions_client and not self.dry_run:
             await self._sessions_client.mark_running(session_id)
 
-        # Set up worktree isolation if enabled
+        # Prepare workspace (git fetch, checkout, branch creation)
         effective_working_dir = self.working_directory
         worktree_branch: str | None = None
         legacy_worktree_name: str | None = None
 
-        if self._worktree_config.enabled:
-            if self._worktree_config.provider == "worktrunk":
-                from steerdev_agent.worktree import WorktrunkClient, compute_branch_name
+        if self._worktree_config.enabled and self._worktree_config.provider == "claude":
+            # Legacy: pass --worktree to Claude CLI (bypasses preparation)
+            legacy_worktree_name = compute_worktree_name(task_id, wave_context)
+            console.print(f"[dim]Using legacy worktree: {legacy_worktree_name}[/dim]")
+        else:
+            from steerdev_agent.workspace.preparation import WorkspacePreparation
 
-                wt_client = WorktrunkClient(self.working_directory)
-                worktree_branch = compute_branch_name(task, wave_context)
-                effective_working_dir = await wt_client.switch(worktree_branch, create=True)
-                console.print(
-                    f"[dim]Worktree: {effective_working_dir} (branch: {worktree_branch})[/dim]"
-                )
-            else:
-                # Legacy: pass --worktree to Claude CLI
-                legacy_worktree_name = compute_worktree_name(task_id, wave_context)
-                console.print(f"[dim]Using legacy worktree: {legacy_worktree_name}[/dim]")
+            preparation = WorkspacePreparation(
+                working_directory=self.working_directory,
+                worktree_config=self._worktree_config,
+                branch_config=self._branch_config,
+            )
+            prep_result = await preparation.prepare(task, wave_context)
+            if not prep_result.success:
+                error_msg = f"Workspace preparation failed: {prep_result.error}"
+                logger.error(error_msg)
+                if self._sessions_client and not self.dry_run:
+                    await self._sessions_client.mark_failed(
+                        session_id, metadata={"error": error_msg}
+                    )
+                return {
+                    "success": False,
+                    "error": error_msg,
+                    "events_sent": self._events_sent,
+                }
+            effective_working_dir = prep_result.working_directory
+            if prep_result.is_worktree:
+                worktree_branch = prep_result.branch_name
+            console.print(
+                f"[dim]Workspace ready: {effective_working_dir} "
+                f"(branch: {prep_result.branch_name})[/dim]"
+            )
+            for warning in prep_result.warnings:
+                console.print(f"[yellow]Warning: {warning}[/yellow]")
 
         # Create executor using factory
         self._executor = ExecutorFactory.create(
@@ -948,19 +977,29 @@ class Runner:
         resolved_wf_id = workflow_id or self.workflow_id
         console.print(f"[dim]Using workflow: {resolved_wf_id}[/dim]")
 
-        # Set up worktree isolation if enabled
+        # Prepare workspace (git fetch, checkout, branch creation)
         effective_working_dir = self.working_directory
         worktree_branch: str | None = None
 
-        if self._worktree_config.enabled and self._worktree_config.provider == "worktrunk":
-            from steerdev_agent.worktree import WorktrunkClient, compute_branch_name
+        from steerdev_agent.workspace.preparation import WorkspacePreparation
 
-            wt_client = WorktrunkClient(self.working_directory)
-            worktree_branch = compute_branch_name(task, wave_context)
-            effective_working_dir = await wt_client.switch(worktree_branch, create=True)
-            console.print(
-                f"[dim]Worktree: {effective_working_dir} (branch: {worktree_branch})[/dim]"
-            )
+        preparation = WorkspacePreparation(
+            working_directory=self.working_directory,
+            worktree_config=self._worktree_config,
+            branch_config=self._branch_config,
+        )
+        prep_result = await preparation.prepare(task, wave_context)
+        if not prep_result.success:
+            error_msg = f"Workspace preparation failed: {prep_result.error}"
+            logger.error(error_msg)
+            return {"success": False, "error": error_msg}
+        effective_working_dir = prep_result.working_directory
+        if prep_result.is_worktree:
+            worktree_branch = prep_result.branch_name
+        console.print(
+            f"[dim]Workspace ready: {effective_working_dir} "
+            f"(branch: {prep_result.branch_name})[/dim]"
+        )
 
         # Build task context for workflow
         task_context = build_workflow_task_context(
@@ -1354,6 +1393,7 @@ async def run_agent(
     force_workflow_id: str | None = None,
     dry_run: bool = False,
     retry_config: RetryConfig | None = None,
+    branch_config: BranchConfig | None = None,
 ) -> dict[str, Any]:
     """Run the steerdev agent.
 
@@ -1377,6 +1417,7 @@ async def run_agent(
         force_workflow_id: Workflow ID override for multi-phase execution.
         dry_run: If True, print the command without executing it.
         retry_config: Retry configuration for failed tasks.
+        branch_config: Branch configuration for git operations.
 
     Returns:
         Run result metadata.
@@ -1399,6 +1440,7 @@ async def run_agent(
         force_workflow_id=force_workflow_id,
         dry_run=dry_run,
         retry_config=retry_config,
+        branch_config=branch_config,
     )
 
     # Install signal handler that kills the subprocess immediately on Ctrl+C

{steerdev-1.0.59 → steerdev-1.0.60}/src/steerdev_agent/setup/templates/skills/steerdev-merge-into-canal-skill/SKILL.md

@@ -18,20 +18,20 @@ Use this skill when a workflow phase tells you to merge the **current task branc
 
 ## Pre-check
 
-Before merging into a canal, verify your current branch has been pushed and has a PR. Do NOT switch branches or sync to main — this skill operates on the current task/wave branch.
+Before merging into a canal, verify your current branch has been pushed and has a PR. Do NOT switch branches or sync to the default branch — this skill operates on the current task/wave branch.
 
 ## Rebase Before Canal Merge
 
-Before merging into the canal, ensure your branch is up to date:
+Before merging into the canal, ensure your branch is up to date. Refer to the **Git Branch Configuration** section in your prompt for the project's default branch name.
 
 ```bash
-git fetch origin main
-git merge-tree --write-tree origin/main HEAD
+git fetch origin <default-branch>
+git merge-tree --write-tree origin/<default-branch> HEAD
 ```
 
 - **If clean** (exit 0): Rebase and force-push with lease:
   ```bash
-  git rebase origin/main
+  git rebase origin/<default-branch>
   git push --force-with-lease origin HEAD
   ```
 - **If conflicts**: Attempt rebase. If it fails on files you did not modify, abort (`git rebase --abort`) and re-queue the task:
@@ -75,6 +75,7 @@ steerdev canal pr CANAL_ID
 - Do not force-push to resolve canal conflicts
 - Do not manually resolve canal merge conflicts outside the supported tooling
 - If canal merge fails, report the blocker with task comments or status updates
+- Replace `<default-branch>` in commands above with the actual branch name from the Git Branch Configuration section
 
 ## Example
 

{steerdev-1.0.59 → steerdev-1.0.60}/src/steerdev_agent/setup/templates/skills/steerdev-single-task-merge-skill/SKILL.md

@@ -14,36 +14,16 @@ Use this skill when a workflow phase tells you to complete **one task on one bra
 - One pull request
 - One task result update that includes the PR URL
 
-## Worktree Mode
+## Workspace Ready
 
-If you are running in a **worktrunk worktree**, you are already on the correct branch in an isolated directory. **Skip branch creation and pre-flight sync** — go directly to implementation.
+The CLI has already prepared your workspace: fetched the latest changes, synced to the default branch, and created or checked out your task branch. **Do not run pre-flight sync steps** — proceed directly to implementation.
 
-## Pre-flight Sync (non-worktree mode only)
-
-If NOT in a worktrunk worktree, sync before creating your task branch:
-
-1. Stash any uncommitted changes (if any):
-   ```bash
-   git stash push -m "steerdev-preflight" 2>/dev/null || true
-   ```
-
-2. Switch to the default branch and pull latest:
-   ```bash
-   git checkout main && git pull origin main --ff-only
-   ```
-   If `main` doesn't exist, try `master`. If `--ff-only` fails (local main diverged), force-reset:
-   ```bash
-   git fetch origin && git reset --hard origin/main
-   ```
-
-3. Now proceed to create your task branch from the up-to-date default branch.
-
-**Why:** The agent may still be on a previous task's branch. Without this step, new branches are created from stale code, causing desync with merged PRs.
+Refer to the **Git Branch Configuration** section in your prompt for the project's default branch name.
 
 ## Workflow
 
 1. Ensure the task is already marked `started`
-2. Create or switch to the task branch (skip if in a worktrunk worktree):
+2. Create or switch to the task branch (if not already on it):
 
 ```bash
 steerdev git branch TASK_ID [--name NAME]
@@ -56,26 +36,26 @@ This fetches the task from the API and builds the branch name automatically:
 
 3. Implement the requested changes
 4. Commit with a conventional commit message that explains why the change exists
-5. Rebase onto the latest target branch before pushing:
+5. Rebase onto the latest default branch before pushing:
 
 ```bash
-git fetch origin main
+git fetch origin <default-branch>
 ```
 
 Dry-run merge check (requires git 2.38+):
 ```bash
-git merge-tree --write-tree origin/main HEAD
+git merge-tree --write-tree origin/<default-branch> HEAD
 ```
 
 - **If exit code 0** (clean merge): Rebase and push:
   ```bash
-  git rebase origin/main
+  git rebase origin/<default-branch>
   git push -u origin HEAD
   ```
 
 - **If exit code non-zero** (conflicts detected): Attempt rebase:
   ```bash
-  git rebase origin/main
+  git rebase origin/<default-branch>
   ```
   - If rebase succeeds after resolving conflicts in files you modified: `git push --force-with-lease origin HEAD`
   - If conflicts are in files you did NOT modify: abort the rebase (`git rebase --abort`) and re-queue the task for a fresh attempt:
@@ -95,22 +75,12 @@ steerdev git pr --title "TITLE" --task-id TASK_ID [--body "BODY"]
 7. Update the task result with the PR URL
 8. Log completion in the root `docs/` progress files
 
-## Branch Naming Convention
-
-Branch names should link to the external ticket tracker (e.g. Linear) for traceability on GitHub:
-
-| Has External ID? | Format | Example |
-|---|---|---|
-| Yes | `task/<TICKET-ID>-<slug>` | `task/PROJ-123-add-user-auth` |
-| No  | `task/<short-uuid>-<slug>` | `task/abc12345-add-user-auth` |
-
-**Why this matters:** GitHub integrations (Linear, Jira, etc.) match ticket IDs in branch names to link PRs/branches back to issues. Using internal UUIDs breaks this linkage.
-
 ## Conventions
 
 - Always use `steerdev git branch` to create branches (it resolves the external ticket ID automatically)
 - Create exactly one PR for the task
 - Include the PR URL in the task result summary
+- Replace `<default-branch>` in commands above with the actual branch name from the Git Branch Configuration section
 
 ## Example
 

{steerdev-1.0.59 → steerdev-1.0.60}/src/steerdev_agent/setup/templates/skills/steerdev-wave-tasks-merge-skill/SKILL.md

@@ -14,28 +14,15 @@ Use this skill when a workflow phase tells you to complete **multiple related ta
 - One shared pull request for the wave
 - All related tasks updated with the same PR URL
 
-## Worktree Mode
+## Workspace Ready
 
-If you are running in a **worktrunk worktree**, you are already on the correct `wave/<N>` branch in an isolated directory. **Skip branch creation and pre-flight sync** — go directly to implementation.
+The CLI has already prepared your workspace: fetched the latest changes, synced to the default branch (for new waves), or stayed on the current wave branch (for continuing waves). **Do not run pre-flight sync steps** — proceed directly to implementation.
 
-## Pre-flight Sync (non-worktree mode only)
-
-If NOT in a worktrunk worktree, check if you need to sync before creating the wave branch:
-
-- **Starting a new wave** (not on `wave/<N>` branch yet): Sync to default branch first:
-  ```bash
-  git stash push -m "steerdev-preflight" 2>/dev/null || true
-  git checkout main && git pull origin main --ff-only
-  ```
-  If `--ff-only` fails: `git fetch origin && git reset --hard origin/main`
-
-- **Continuing a wave** (already on `wave/<N>` branch): Do NOT switch to main. Stay on the wave branch and continue with the next task.
-
-**Why:** The agent may still be on a previous task/wave branch. New waves must branch from updated main. Mid-wave tasks must stay on the wave branch.
+Refer to the **Git Branch Configuration** section in your prompt for the project's default branch name.
 
 ## Workflow
 
-1. Create or switch to the shared wave branch (skip if in a worktrunk worktree):
+1. Create or switch to the shared wave branch (if not already on it):
 
 ```bash
 git checkout -b wave/<wave-number>
@@ -54,26 +41,26 @@ git commit -m "[PROJ-123] feat: add user endpoint"
 git commit -m "[task:abc12345] feat: add user endpoint"
 ```
 
-3. After the wave work is ready for review, rebase onto the latest target branch:
+3. After the wave work is ready for review, rebase onto the latest default branch:
 
 ```bash
-git fetch origin main
+git fetch origin <default-branch>
 ```
 
 Dry-run merge check (requires git 2.38+):
 ```bash
-git merge-tree --write-tree origin/main HEAD
+git merge-tree --write-tree origin/<default-branch> HEAD
 ```
 
 - **If exit code 0** (clean merge): Rebase and push:
   ```bash
-  git rebase origin/main
+  git rebase origin/<default-branch>
   git push -u origin HEAD
   ```
 
 - **If exit code non-zero** (conflicts detected): Attempt rebase:
   ```bash
-  git rebase origin/main
+  git rebase origin/<default-branch>
   ```
   - If rebase succeeds after resolving conflicts in files you modified: `git push --force-with-lease origin HEAD`
   - If conflicts are in files you did NOT modify: abort the rebase (`git rebase --abort`) and re-queue the current task:
@@ -110,6 +97,7 @@ Run `steerdev tasks get TASK_ID` to find the task's `linear_identifier` before c
 - Do not create per-task PRs inside the wave
 - Keep commits traceable by including the external ticket ID (or internal ID fallback) in each commit
 - Include the shared PR URL in every related task result
+- Replace `<default-branch>` in commands above with the actual branch name from the Git Branch Configuration section
 
 ## Example
 

{steerdev-1.0.59 → steerdev-1.0.60}/src/steerdev_agent/setup/templates/steerdev.yaml

@@ -72,6 +72,11 @@ worktrees:
   # Commands to run in pre-merge hook (empty = use worktrunk.config.toml defaults)
   pre_merge_checks: []
 
+# Branch configuration for git operations
+branches:
+  # Default branch for sync, rebase, and PR targets (e.g. main, dev, develop)
+  default_branch: main
+
 # Evidence reports: submit a review-ready report after each task/workflow
 evidence:
   enabled: true