Rootwork

Rootwork is a workspace scaffold for Worktrunk.

• Rootwork sets up the project layout.
• Worktrunk does the actual worktree operations.
• Rootwork adds project-local AI context so agents understand the layout.

Current implementation note:

• The active runtime is still the shell implementation.
• There is an in-progress Go rewrite in cmd/rwt, internal/, and go.mod.
• Go is not required to use Rootwork today.
• If behavior changes, keep the shell implementation and the Go implementation aligned until the Go version becomes the packaged runtime.

Layout

~/Projects/MyProject/
  .worktree-config.yml
  AGENTS.md
  .agents/
  repos/
    MyProject/
  trees/
    feature-auth
    bugfix-login

Git and Worktrunk branches stay normal:

feature/auth
bugfix/login

Worktrunk places them in flattened tree directories using sanitize:

trees/feature-auth
trees/bugfix-login

Rootwork manages this Worktrunk user-config line:

worktree-path = "{{ repo_path }}/../../trees/{{ branch | sanitize }}"

Step 1: Set Up A New Machine

From this repo:

cd ~/Dev/Projects/rootwork
./bootstrap-machine

What it does:

1. Installs the global rwt command
2. Checks whether your bin dir is on PATH
3. Refreshes Worktrunk shell integration
4. Creates or updates your Worktrunk user config
5. Sets the Rootwork worktree-path

If wt is missing, the script stops and tells you how to install it.

After that:

source ~/.zshrc
type wt
command -v rwt

If command -v rwt prints nothing, your shell has not picked up the new PATH yet.

Step 2: Create A New Project

Create and enter the project directory first:

mkdir -p ~/Projects/MyDashboard
cd ~/Projects/MyDashboard

Then scaffold the current directory and clone the app repo:

rwt init-project --git git@github.com:org/my-dashboard.git

Then validate it:

cd ~/Projects/MyDashboard
rwt doctor

You should now have:

~/Projects/MyDashboard/
  .worktree-config.yml
  AGENTS.md
  .agents/
  repos/
    MyDashboard/
  trees/

Step 3: Adopt An Existing Project

If a project already has the right directory structure and real repo location:

cd ~/Projects/MyDashboard
rwt adopt-project

Then validate it:

cd ~/Projects/MyDashboard
rwt doctor

Use --force only if you want to overwrite Rootwork-managed files that already exist.

Step 4: Do Daily Work

Rootwork does not manage worktrees directly.

Run Worktrunk inside the real repo:

cd ~/Projects/MyDashboard/repos/MyDashboard
wt switch --create feature/auth
wt list
wt remove

Step 5: Check The Setup

From a project root:

cd ~/Projects/MyDashboard
rwt doctor

rwt doctor verifies:

1. .worktree-config.yml exists
2. repos/<ProjectName> exists
3. the repo directory is a git repo
4. trees/ exists
5. wt is installed
6. Worktrunk user config exists
7. Worktrunk worktree-path matches the Rootwork layout

It also reminds you to verify shell integration manually with:

type wt

If rwt doctor fails on the Worktrunk path setting, re-run:

cd ~/Dev/Projects/rootwork
./bootstrap-machine

Quick Start

cd ~/Dev/Projects/rootwork
./bootstrap-machine

rwt init-project MyDashboard --git git@github.com:org/my-dashboard.git
cd ~/Projects/MyDashboard
rwt doctor

cd repos/MyDashboard
wt switch --create feature/auth
wt list
wt remove

Rootwork Commands

rwt doctor
rwt init-project [--git <url>] [--git-branch <branch>]
rwt adopt-project [--repo-dir <relative-path>] [--base <branch>] [--force]
rwt install-global [target-bin-dir]
rwt uninstall-global [target-bin-dir]

Agent Context

Generated and adopted workspaces include:

• AGENTS.md
• .agents/skills/rootwork-project-ops/

That gives future AI sessions project-local instructions about the Rootwork layout and the expected Worktrunk workflow.

Maintain This Tool

• Public entrypoint: rwt
• Internal implementation scripts live under libexec/
• Shared helpers live under lib/
• Project workspace scaffold files live under scaffold/project-root/