/configure-workspaces

name: configure-workspaces
description: Propose and generate workspace configuration files (.humanlayer/workspace.json and .humanlayer/workspace.local.json) for a repository

Purpose

This skill reads the project, proposes a concise workspace configuration, writes the approved files, and validates them.

The workspace config files control how worktrees are created when tasks use `workspaceTiming = now` in the Riptide task creation UI:

• `.humanlayer/workspace.json` — shared team configuration, safe to commit
• `.humanlayer/workspace.local.json` — machine-specific overrides, gitignored

Use plain, brief language. State each point as one human speaking to another.

Steps to follow

<step index=0>

Step 0: Select the repository

Check the current directory and home directory:

Bash(pwd)
Bash(printf '%s\n' "$HOME")
Bash(git rev-parse --show-toplevel)

If `git rev-parse` succeeds, use that repository root as the working directory. State the path in one short sentence.

If the current directory is the home directory and it is not inside a Git repository, ask one question:

Which repository should I configure? Send its path.

Use the same question when the current directory is not a Git repository. After the user gives a path, confirm it with `git -C <path> rev-parse --show-toplevel` and use the returned root.

</step>

<step index=1>

Step 1: Read the project

Read any existing workspace config files:

Read(.humanlayer/workspace.json)
Read(.humanlayer/workspace.local.json)

Run all file reads and commands from the selected repository root.

Check for coordination-repo signals (Claude config, additional sibling repos):

Read(.claude/settings.json)
Bash(ls -la ../)
Read(package.json)
Read(Makefile)
Read(README.md)
Bash(git remote -v)

Use an existing workspace config as the starting point. Infer changes from the repository and the user's request.

</step>

<step index=2>

Step 2: Build the proposal

Infer a complete proposal from project files and common defaults.

• Use a single-repository config unless the project clearly coordinates related sibling repositories.
• For one repository, use `{ "localPath": ".", "primary": true }`.
• For multiple repositories, include the related paths and mark exactly one primary repository.
• Prefer the repository with the team's central Claude settings, MCP config, or agent policy as primary.
• Use `~/.humanlayer/workspaces/{{ TASKSLUG }}/{{ REPOBASENAME }}` as the default path template.
• Use `origin/main` as the default source ref, or whatever default remote the user prefers (e.g. upstream/main - if there are multiple remotes, ask)
• Infer a setup command from project scripts, package manager files, the Makefile, and the README.
• Include local files that exist and are useful in a worktree, such as `.env`, `.env.local`, `.env.development.local`, `.claude/settings.local.json`, and `.humanlayer/workspace.local.json`.
• Put machine-specific values in `.humanlayer/workspace.local.json`.

For multi-repository workspaces:

• Sessions in the workspace launch in the primary repo's worktree by default.
• Skills and instruction files (`CLAUDE.md`/`AGENTS.md`) are loaded from **all** repos in the workspace.
• Repo-local `.claude/settings*.json` / MCP-style configuration only governs sessions launched from a repo — so the repo holding the team's central Claude settings, MCP config, or agent policy should usually be primary.

The first response after project inspection must show the proposed `.humanlayer/workspace.json` as a fenced `json` block. If local overrides are useful, show `.humanlayer/workspace.local.json` in a second fenced `json` block. End with one short line:

Tell me what to change, or approve this config.

When the user gives feedback, update and print the complete proposed JSON again.

</step>

<step index=3>

Step 3: Validate the proposal

Validate the proposed config before asking for approval.

**For single-repo projects, workspace.json looks like:**

{
  "disabled": false,
  "pathTemplate": "~/.humanlayer/workspaces/{{ TASKSLUG }}/{{ REPOBASENAME }}",
  "branchTemplate": "{{ TASKSLUG }}",
  "sourceRef": "origin/main",
  "setupCommand": "",
  "copyGlobs": [
    ".env",
    ".env.local",
    ".env.development.local",
    ".claude/settings.local.json",
    ".humanlayer/workspace.local.json"
  ],
  "repos": [
    {
      "localPath": ".",
      "description": "Selected repository",
      "primary": true
    }
  ]
}

**For multi-repo projects (coordination repos), workspace.json looks like:**

{
  "disabled": false,
  "pathTemplate": "~/.humanlayer/workspaces/{{ TASKSLUG }}/{{ REPOBASENAME }}",
  "branchTemplate": "{{ TASKSLUG }}",
  "sourceRef": "origin/main",
  "setupCommand": "bun install",
  "copyGlobs": [
    ".env",
    ".env.local",
    ".humanlayer/workspace.local.json"
  ],
  "repos": [
    {
      "localPath": ".",
      "description": "Coordination repo",
      "primary": true
    },
    {
      "localPath": "../api",
      "description": "API service",
      "setupCommand": "bun install"
    },
    {
      "localPath": "../web",
      "description": "Web frontend",
      "sourceRef": "origin/main"
    }
  ]
}

**Config rules to follow:**

• Multi-repo configs should mark exactly one repo with `"primary": true` — sessions launch in the primary repo's worktree by default, and its repo-local Claude/MCP configuration governs sessions. If no repo is marked, the task form asks the user to pick one.
• `localPath: "."` refers to the selected repository itself (the one containing this config); other entries are sibling paths relative to it
• Template variables are `{{ TASKSLUG }}` and `{{ REPOBASENAME }}` only
• `copyGlobs` is additive with de-duplication (defaults → workspace.json → workspace.local.json → per-repo), never replaced
• Repo entries may override `sourceRef`, `setupCommand`, `copyGlobs`, and `primary` — `branchTemplate` is always root-level
• `$patc