Transition to Git-Native Workflow (Branch-per-Track & Worktrees)

[sherzat3]

Context & Problem

Currently, Conductor operates as a file-based state manager. When a user creates a new track, the artifacts (spec.md, plan.md) and the implementation changes all live in the current working directory (under conductor/tracks/).

This presents a few limitations:

• Context Contamination: It is difficult to work on multiple tracks simultaneously without artifacts or code changes from one track bleeding into another.
• Serial Workflow: Users cannot easily run an agent on a long-running implementation task in the background while manually working on a different feature.

Proposal: Git-Native Architecture

The proposal is to move Conductor to a Branch-per-Track model, where every "Track" is synonymous with a specific Git branch.

1. Branch-per-Track

When running /conductor:newTrack, the extension should:

1. Create a new branch (e.g., conductor/track-<id>-<slug>).
2. Switch to that branch immediately.
3. Generate the spec.md and plan.md inside that branch.

This ensures that the "Planning" phase becomes part of the feature's commit history, and the main branch remains clean of work-in-progress artifacts.

2. Experimental: Git Worktree Support

To enable true parallelism, we should explore supporting Git Worktrees.
Instead of just switching branches (which updates the current directory), Conductor could offer a mode to spin up a worktree.

This would create a sibling directory (e.g., ../project-track-01) checked out to that track's branch. This allows a user to run one track in the worktree folder while continuing to work on another track in the main folder.

Open Design Questions

The biggest challenge with this approach is Discovery/Registry.
Currently, conductor/tracks.md acts as a central registry of all work. If we move to a branch-based model, the main branch will technically not know that track-02 exists on a divergent branch.

Possible solutions to discuss:

• Dynamic Discovery: The /conductor:status command stops reading tracks.md and instead scans git branch --list conductor/*, parsing the metadata from the tip of those branches.
• Hybrid: We continue to commit a registry line to main when a track is created, even if the work happens elsewhere.

Discussion points:

I am looking for feedback on:

1. Does the worktree complexity outweigh the benefits for your workflow?
2. How should we handle the "Global Status" view if state is scattered across branches?
3. Are there edge cases in CI/CD pipelines we need to consider?

[jtmcdole]

For larger projects (e.g. Flutter) - if you don't get fetch --all you won't get all the information from the upstream repo (iirc, tags are the major problem).

I love work trees, enough that I built this to automatically setup Flutter for developers: https://github.com/jtmcdole/flutter_worktree/ The key is the .bare checkout and root .git pointer.

Question for you: how do you envision this working with multiple people working on a project? If I'm working in a fork, I can keep my own tracks, clear them out when I make a pull request. If we're expecting teams to have a series of tracks - how are they discoverable on the upstream fork if they are in branches?

What about permission around branch creation?

[petrmvala]

I think this is quite an important feature for several reasons.

1. Context isolation
2. Sandboxing
3. Checkpointing

The first you described in the issue description so I would touch on the other two.

What I mean by checkpointing is committing the developed changes once they hit some satisfying state to which I could eventually like to return to. Git is great for that of course. The problem is that when I'm operating under my git identity/configuration, I have permissions to sign commits on my behalf, I might also be able to push them to production branches in some repositories. Therefore, allowing any tool to run git commands is a big waving security red flag for me.

Removing git configuration in the respective repo is not feasible as then I would have to set it up again in order to commit myself. This brings me to sandboxing. I think that checking out the repository into a different directory via git worktree and running a sandboxed gemini in there is a good way to achieve both:

• We would have a way to checkpoint the development from the gh repository
• Gemini could not push to the remote as it would not have the same git config (worktree .gitconfig is a symlink to original worktree and that directory is out of sandbox). To be verified.

[thedatadavis]

Re: Branch-per-track

I just added the following to conductor/workflows.md (prepended before the Task Workflow) and gave it a try; it worked as intended:

## Track Initialization Workflow

Before a new track is implemented, it must be initialized and planned on a dedicated planning branch.

1. **Create Planning Branch:**
   - Create and switch to a new branch for planning.
   - **Naming Convention:** `plan/track-name` (e.g., `plan/api-modernization`).
   - **Command:** `git checkout -b plan/<track-name>`

2. **Generate Track Artifacts:**
   - Follow the `NEW TRACK INITIALIZATION` protocol to gather requirements and generate the `spec.md`, `plan.md`, `index.md`, and `metadata.json` within the tracks directory.

3. **Commit Planning Artifacts:**
   - Stage the new track directory and the updated `tracks.md`.
   - **Action:** Commit these changes with a descriptive message (e.g., `docs(conductor): Initialize track 'API Modernization'`).

4. **Generate Planning Pull Request:**
   - **Action:** Push the planning branch: `git push origin plan/<track-name>`.
   - **Action:** Use the `gh` CLI to create a Pull Request using the **Pull Request Template**.
   - **Purpose:** This allows the user to review and approve the **Specification** and **Implementation Plan** before any application code is written.

5. **Approval & Merge:**
   - The user will manually review and merge the planning PR on GitHub.
   - Once merged, switch back to `main`, pull the changes, and proceed to the **Task Workflow** for implementation.

Notably, it's just me with a small project, working serially across tracks. For one-offs/offshoots, I use the Jules to handle smaller tasks in separate threads.