Scaffold Workspace

Step 2: Validate

1. Confirm ~/workspace/<project>/ exists and is a git repo
2. Check whether ~/workspace/<project>_workspace/ already exists
   • If it does → skip to Add Initiative to Existing Workspace (at the bottom of this doc)
   • If it doesn't → proceed with full workspace creation
3. Confirm the branch name doesn't already exist in the project repo: cd ~/workspace/<project> && git branch --list <branch_name>

Step 3: Create the Workspace Structure

mkdir -p ~/workspace/<project>_workspace
cd ~/workspace/<project>_workspace
git init
mkdir -p workbench/<initiative_name>
mkdir -p .cursor/rules
mkdir -p .cursor/skills

Write .gitignore

# Worktree directories (created from ~/workspace/<project>)
<project>-*/

# OS files
.DS_Store
*.swp
*.swo

# Large data files
*.csv
*.parquet

Step 4: Create the Git Worktree

cd ~/workspace/<project>
git worktree add ~/workspace/<project>_workspace/<project>-<initiative_slugified> -b <branch_name>

Where <initiative_slugified> converts underscores to hyphens (e.g., coverage_transfer_bug → coverage-transfer-bug).

Step 5: Create the .code-workspace File

Write to ~/workspace/<project>_workspace/workbench/<initiative_name>/<initiative_name>.code-workspace:

{
  "folders": [
    {
      "name": "worktree: <project>-<initiative_slugified>",
      "path": "../../<project>-<initiative_slugified>"
    },
    {
      "name": "workbench: <initiative_name>",
      "path": "."
    }
  ],
  "settings": {}
}

If the user specified reference projects, add entries for each:

{
  "name": "ref: <ref_project> (read-only)",
  "path": "../../../<ref_project>"
}

The path ../../../<ref_project> navigates from workbench/<initiative>/ up to ~/workspace/ and into the reference project.

Step 6: Create the Cursor Rule

Write to ~/workspace/<project>_workspace/.cursor/rules/commit-only-in-worktree.mdc:

# Commit Only in Worktrees

When working in this workspace, ONLY commit code changes to git worktree directories (folders matching `<project>-*/`). Never commit directly to the main project repository at `~/workspace/<project>/`.

## Rules

1. All code changes (features, bug fixes, refactors) MUST be committed in the worktree directory for the current initiative.
2. The workbench directory is tracked by this workspace's own git repo — workbench changes (docs, plans, output) are committed to the workspace repo at `~/workspace/<project>_workspace/`.
3. Never run `git push` from within a worktree without explicit user approval.
4. When creating new files, place them in the correct git context:
   - Code files → worktree directory
   - Documentation, plans, analysis output → workbench initiative folder
5. Before committing, verify you are in the correct directory by checking `git remote -v` — the worktree remote should point to the project's GitLab origin, not the workspace repo.

Step 7: Check for Project-Specific Setup Skill

Check if ~/workspace/<project>_workspace/.cursor/skills/<project>-worktree-setup/SKILL.md exists.

• If it exists: Tell the user: "Found a project-specific worktree setup skill for <project>. Running it now..." and follow its instructions to configure the new worktree.
• If it doesn't exist: Ask the user: "No project-specific setup skill found for <project>. Some projects need special worktree setup (Docker config, .env files, credential scripts, etc.). Want to create a setup skill now?" If yes, scaffold a SKILL.md at .cursor/skills/<project>-worktree-setup/SKILL.md by asking what setup steps are needed for this project's worktrees.

Step 8: Create the Workspace README

Write to ~/workspace/<project>_workspace/README.md:

# <project>-workspace

Workspace for <project>-focused investigations and feature work. Worktrees are created from `~/workspace/<project>/` (the main clone).

## Structure

- `workbench/` — Planning docs, analysis scripts, experiments (tracked in this repo)
- `<project>-<branch>/` — Git worktrees for active work (created from main clone)
- `.cursor/rules/` — Workspace-level Cursor rules
- `.cursor/skills/` — Project-specific Cursor skills

## Setup

```bash
# Open an initiative in Cursor with scoped context
cursor ~/workspace/<project>_workspace/workbench/<initiative_name>/<initiative_name>.code-workspace

# Create a new worktree for a feature/bug
cd ~/workspace/<project>
git worktree add ~/workspace/<project>_workspace/<project>-<feature> -b build-jw-<feature>

Active Worktrees

Git Repositories

Cleanup

When done with a worktree:

cd ~/workspace/<project>
git worktree remove ~/workspace/<project>_workspace/<project>-<feature>

# Update the Active Worktrees table above
# Remove its entry from the relevant .code-workspace file

## Step 9: Initial Commit

```bash
cd ~/workspace/<project>_workspace
git add .
git commit -m "Initialize <project> workspace with <initiative_name> workbench"

Step 10: Summary

Tell the user:

1. Workspace created at ~/workspace/<project>_workspace/
2. Worktree created at ~/workspace/<project>_workspace/<project>-<initiative_slugified>/ on branch <branch_name>
3. Open in Cursor: cursor ~/workspace/<project>_workspace/workbench/<initiative_name>/<initiative_name>.code-workspace
4. Workbench initiative folder: ~/workspace/<project>_workspace/workbench/<initiative_name>/

Add Initiative to Existing Workspace

If ~/workspace/<project>_workspace/ already exists, add a new initiative without re-creating the workspace:

1. Ask for initiative name, branch name, and reference projects (same as Step 1)
2. Create workbench/<initiative_name>/ directory
3. Create the worktree:

   cd ~/workspace/<project>
   git worktree add ~/workspace/<project>_workspace/<project>-<initiative_slugified> -b <branch_name>
   

4. Create the .code-workspace file in workbench/<initiative_name>/
5. Update .gitignore — add the new worktree directory pattern if not already covered by the glob
6. Update README.md — add a row to the Active Worktrees table
7. Run the project-specific setup skill if it exists at .cursor/skills/<project>-worktree-setup/SKILL.md
8. Commit:

   cd ~/workspace/<project>_workspace
   git add .
   git commit -m "Add <initiative_name> initiative with worktree <project>-<initiative_slugified>"