fix(workspace): move worktree path outside repo dir and add branch prefix option

[amondnet]

Summary

• Move git worktrees from <repoDir>/.claude/worktrees/ to <workspace.root>/github-<owner>-<repo>/worktrees/ to prevent unstaged changes from blocking before_run hook rebase operations
• Strip leading # from issue identifiers (#42 → 42 instead of _42) for cleaner branch names
• Add workspace.branch_prefix config option for custom branch name prefixes (e.g. agent-please/42)

Test plan

• All existing workspace/worktree tests updated and passing (708 tests, 703 pass, 5 pre-existing redis/ioredis failures)
• New tests for resolveWorktreePath, applyBranchPrefix, sanitizeIdentifier # stripping, and branch_prefix integration
• Lint passes cleanly

---

Summary by cubic

Move git worktrees outside repo clones and add workspace.branch_prefix for custom branch names. Strip a leading # from identifiers; the prefix applies only to the branch name, not the worktree path.

• Bug Fixes

  • Place worktrees at <workspace.root>/github-<owner>-<repo>/worktrees/ so unstaged changes in the clone no longer block rebases.
  • Fix @chat-adapter/state-ioredis integration by calling createIoRedisState; make error-path tests reliable by mocking missing adapters.
  • Reuse resolveRepoDir in resolveWorktreePath to reduce duplication; include workspace.branch_prefix in test fixtures.

• New Features

  • Strip leading # from identifiers for branch names (e.g., #42 → 42).
  • Add workspace.branch_prefix to customize branch names (e.g., agent-please/42); worktree paths use only the sanitized identifier.

^{Written for commit 55233c9. Summary will update on new commits.}

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request focuses on improving workspace management by relocating worktrees, sanitizing issue identifiers for branch names, and introducing a configurable branch prefix. These changes aim to enhance the flexibility and robustness of the workspace functionality.

Highlights

• Worktree Path: Moved git worktrees to prevent before_run hook rebase blocking.
• Issue Identifiers: Stripped leading # from issue identifiers for cleaner branch names.
• Branch Prefix: Added workspace.branch_prefix config option for custom branch name prefixes.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[cubic-dev-ai]

1 issue found across 6 files

Confidence score: 4/5

• This PR is likely safe to merge; the reported issue is in packages/core/src/workspace.test.ts and appears test-specific rather than a runtime behavior bug.
• The most severe issue is that the “empty string” branch-prefix test uses null instead of '', which weakens coverage for the intended edge case and could let a related regression slip through.
• Given the moderate-low severity (4/10) and high confidence, risk is minimal but worth a quick test fix before relying on this case.
• Pay close attention to packages/core/src/workspace.test.ts - the branch-prefix edge-case assertion is targeting the wrong input type.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/core/src/workspace.test.ts">

<violation number="1" location="packages/core/src/workspace.test.ts:217">
P2: The “empty string” branch-prefix test passes `null` instead of `''`, so it does not test the intended behavior.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Config as Config Loader
    participant WS as Workspace Service
    participant Git as Git CLI
    participant FS as Filesystem

    Note over Config, FS: Workspace Creation Flow

    Config->>Config: NEW: Load workspace.branch_prefix
    
    WS->>WS: CHANGED: sanitizeIdentifier(id)
    Note right of WS: Strips leading '#' from IDs<br/>(e.g., #42 -> 42)
    
    WS->>WS: NEW: applyBranchPrefix(prefix, sanitizedId)
    Note right of WS: Combines prefix + ID<br/>(e.g., agent/42)

    WS->>FS: resolveRepoDir(workspaceRoot, repoUrl)
    FS-->>WS: path: <root>/github-<owner>-<repo>

    WS->>Git: ensureSharedClone(repoDir, repoUrl)
    opt Clone missing
        Git->>FS: Create repo directory
        Git->>Git: git clone --mirror
    end

    WS->>WS: NEW: resolveWorktreePath(...)
    Note right of WS: Calculates path OUTSIDE of repoDir<br/>to <root>/<repo>/worktrees/<id>

    WS->>FS: Check if wtPath exists
    FS-->>WS: result

    alt Worktree does not exist
        alt NEW: Branch prefix or ID used
            WS->>Git: CHANGED: git worktree add (wtPath) -b (branchName)
        else issue.branch_name provided
            WS->>Git: CHANGED: git worktree add (wtPath) (issue.branch_name)
        end
        Git-->>WS: success
    end

    Note over WS, Git: Workspace Cleanup Flow

    WS->>WS: NEW: resolveWorktreePath(...)
    WS->>Git: CHANGED: git worktree remove (wtPath)
    WS->>FS: Delete worktree directory
    Git-->>WS: success

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[gemini-code-assist]

Code Review

This pull request refactors the worktree path to be outside the main repository clone, which is a good move to prevent conflicts with unstaged changes. It also introduces a configurable branch prefix and improves branch name sanitization. The changes are well-tested. I have one suggestion to reduce code duplication for better maintainability.

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/core/src/workspace.test.ts">

<violation number="1" location="packages/core/src/workspace.test.ts:877">
P2: This test conditionally skips the path assertion when `createWorkspace` returns an `Error`, so failures can be masked. Assert non-error first, then check `result.path`.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

0 issues found across 3 files (changes from recent commits).

_{Requires human review: Auto-approval blocked by 1 unresolved issue from previous reviews.}

[cubic-dev-ai]

0 issues found across 4 files (changes from recent commits).

_{Requires human review: Auto-approval blocked by 1 unresolved issue from previous reviews.}

[sonarqubecloud]

Quality Gate failed

Failed conditions
1 Security Hotspot

See analysis details on SonarQube Cloud

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

_{Requires human review: This PR modifies core workspace and git worktree management logic, including directory structure changes and branch naming sanitization, which requires human oversight.}