a-green-hand-jack/new-workspace

Create New Git Workspace

Before Acting — Mandatory

1. Detect current scope: run git rev-parse --git-common-dir vs --show-toplevel to confirm which repo you are operating on. In a project-control-root layout, identify whether the target is the root repo, code/, or paper/.
2. Read project memory if memory/BRIEFING.md exists:
   • memory/BRIEFING.md — current phase and active worktrees
   • memory/project-conventions.md — worktree naming policy and path conventions for this project
3. Check existing worktrees with git worktree list before creating a new one to avoid name collisions or orphaned worktrees.

Skipping step 2 risks placing the worktree in the wrong path or using a name that conflicts with an existing branch or worktree policy.

---

Create a branch or Git worktree without confusing project-level management with component-repo management.

Use this skill for:

• code, experiment, baseline, feature, debug, or rebuttal implementation branches
• paper venue branches such as NeurIPS, ICML, ICLR, CVPR, ACL, or EMNLP submissions
• arXiv paper releases
• camera-ready paper versions

In a full research project, code worktrees should live under <ProjectName>/code-worktrees/, and paper worktrees should live under <ProjectName>/paper-worktrees/.

Pair this skill with:

• safe-git-ops for non-trivial Git state, conflicts, or sandbox write failures
• research-project-memory to record worktree purpose and exit condition
• remote-project-control when a code worktree will be used on an SSH/HPC server
• run-experiment when the new workspace immediately launches jobs
• submit-paper when a paper worktree is for a submission, arXiv, or camera-ready version
• camera-ready-finalizer when a paper worktree is for an accepted version

Core Principles

• Create worktrees for component repos, not for the whole project root.
• Prefer sibling code worktrees under <ProjectName>/code-worktrees/.
• Prefer sibling paper worktrees under <ProjectName>/paper-worktrees/.
• Avoid nested worktrees inside code/ or paper/ unless the user explicitly requires that layout.
• Every research worktree should have a purpose, linked claim/risk/experiment, and exit condition.
• Paper worktrees should also record target venue/version, submission mode, template/style differences, cleanup requirements, and source-visibility assumptions.
• Paper source visibility is independent of venue. A paper worktree may be agent-private, author-visible, anonymous-submission, public-preprint, camera-ready-public, or publisher-artifact.
• experiments/ is runnable logic; stable result summaries belong in docs/results/, reports in docs/reports/, and run pointers in docs/runs/.
• Code worktrees under the same project-control root should reuse one shared code uv environment by default; paper worktrees do not need a local TeX install by default. Use a worktree-specific uv environment only for dependency changes, incompatible Python/CUDA stacks, destructive package tests, or a real concurrent sync/race risk.

Step 1 - Classify the Target

Ask the user for:

• workspace type: branch or worktree
• component: code or paper
• branch type:
  • code: feature, exp, baseline, debug, rebuttal, or custom
  • paper: venue, submission, arxiv, camera-ready, rebuttal, paper-fix, or custom
• branch name without prefix
• target repo path, if not obvious
• for paper workspaces: source visibility tier, audience, sync target, and cleanup gate
• whether to write worktree memory

If running inside <ProjectName>/, prefer the code/ repo for experiment, baseline, debug, and rebuttal implementation work. Prefer the paper/ repo for venue retargeting, arXiv releases, camera-ready versions, source cleanup, paper-only rebuttal edits, or submission formatting.

If running inside <ProjectName>/code/, infer:

code repo root:      <ProjectName>/code/
project control root: <ProjectName>/
worktree root:      <ProjectName>/code-worktrees/

If running inside <ProjectName>/paper/, infer:

paper repo root:      <ProjectName>/paper/
project control root: <ProjectName>/
worktree root:        <ProjectName>/paper-worktrees/

If running inside a standalone code repo, use the fallback worktree root:

<code-repo-parent>/worktrees/

If running inside a standalone paper repo, use the fallback worktree root:

<paper-repo-parent>/paper-worktrees/

Step 2 - Verify Git State

In the target repo:

git -C <repo-root> rev-parse --show-toplevel
git -C <repo-root> status --short
git -C <repo-root> branch --show-current
git -C <repo-root> worktree list

If there are uncommitted changes, ask whether to commit, stash, continue with a branch only, or cancel.

Step 3 - Choose Branch Name

Use:

<branch-type>/<branch-name>

Examples:

• exp/new-loss
• baseline/fair-tuning
• debug/nan-loss
• rebuttal/add-ablation
• feature/data-loader
• venue/neurips
• venue/icml
• arxiv/v1
• camera-ready/neurips
• private/draft
• overleaf/main-clean

The worktree directory name should be filesystem-friendly:

<branch-type>-<branch-name-with-slashes-replaced-by-hyphens>

Step 4 - Create a Branch

For branch-only work:

git -C <repo-root> checkout -b <branch-type>/<branch-name>

Then update component memory if the branch has a research purpose.

Step 5 - Create a Worktree

Determine the worktree root:

For code:

1. If <repo-root> is <ProjectName>/code/, use <ProjectName>/code-worktrees/.
2. If <repo-root>/../code-worktrees/ exists, use that.
3. If project memory declares a code worktree root, use that.
4. Otherwise use <repo-root>/../worktrees/.

For paper:

1. If <repo-root> is <ProjectName>/paper/, use <ProjectName>/paper-worktrees/.
2. If <repo-root>/../paper-worktrees/ exists, use that.
3. If project memory declares a paper worktree root, use that.
4. Otherwise use <repo-root>/../paper-worktrees/.

Create the worktree:

mkdir -p <worktree-root>
git -C <repo-root> worktree add <worktree-root>/<worktree-dir-name> -b <branch-type>/<branch-name>

If the branch already exists, ask whether to create the worktree from the existing branch:

git -C <repo-root> worktree add <worktree-root>/<worktree-dir-name> <branch-type>/<branch-name>

Step 6 - Copy Local Tooling and Link Shared Assets

Copy local IDE/tooling directories when present:

.vscode/
.cursor/
.claude/

Copy, do not symlink, because each worktree may need independent IDE state.

If <repo-root>/.worktree-links exists, read relative paths from it and symlink shared large assets into the worktree. Typical entries:

data/
models/
.env
configs/local_settings.yaml

Use absolute symlink targets so links remain valid from the worktree path.

Step 7 - Prepare Component-Specific Paths

Code Worktrees

In the worktree, ensure:

docs/results/
docs/reports/
docs/runs/
.agent/

Use these paths for branch-local evidence:

• docs/results/: stable result summaries, table notes, figure notes
• docs/reports/: experiment reports and result narratives
• docs/runs/: job IDs, config paths, commit hashes, remote paths, short metrics
• .agent/worktree-status.md: purpose, linked claims/risks, latest reliable state, exit condition

Do not store raw logs, checkpoints, wandb runs, tensorboard caches, or large outputs in docs/.

Paper Worktrees

In a paper worktree, ensure:

.agent/

Create or update .agent/worktree-status.md with paper-version fields:

• target venue or release: NeurIPS, ICML, ICLR, CVPR, ACL, EMNLP, arXiv, camera-ready
• submission mode: anonymous, preprint, camera-ready, rebuttal, or internal
• style/template differences from main paper
• source visibility tier:
  • agent-private: may contain .agent/, AGENTS.md, CLAUDE.md, writing memory, provenance notes, internal result docs, CSVs, and plotting scripts; should not sync to Overleaf/public remotes
  • author-visible: coauthor/Overleaf-visible; must exclude .agent/, AGENTS.md, CLAUDE.md, raw CSVs, internal docs, plotting scripts, reviewer strategy, and private paths
  • anonymous-submission: venue/source-upload-visible; must enforce anonymity and exclude agent/private files
  • public-preprint: arXiv/public source; must be public-clean
  • camera-ready-public: final accepted public/publisher source; must be de-anonymized and public-clean
  • publisher-artifact: final public source plus artifact/release-facing files only
• audience and sync target: none, Overleaf-GitHub, GitHub, submission-system, arXiv, publisher, or artifact
• allowed paths and forbidden paths
• cleanup gate: before-push, before-submission, before-arxiv, before-camera-ready, or before-release
• cleanup requirements:
  • arXiv/public source: remove TODOs, author comments, reviewer notes, internal figure/table descriptions in TeX comments, hidden notes, and anonymization leftovers
  • author-visible / Overleaf: remove or avoid .agent/, AGENTS.md, CLAUDE.md, raw CSVs, internal result docs, plotting scripts, private paths, and agent-only notes
  • conference anonymous: enforce anonymity and venue format; source comments may still be risky if the source is uploaded, so do not rely on them
  • camera-ready: de-anonymize, add acknowledgements/funding, close rebuttal promises, and remove draft-only notes
• source-format gate: tex-fmt --check --nowrap --recursive . when tex-fmt is installed; format with tex-fmt --nowrap --recursive . only after the user requests it or the project policy requires it
• Overleaf/GitHub compile status and branch mapping, if used

Do not copy code-side docs/results/, docs/reports/, or docs/runs/ conventions into paper worktrees unless the user explicitly wants paper-local notes. Prefer .agent/ for paper-version memory and root memory/ for durable cross-version state.

Step 8 - Sync Environment

For code worktrees, if pyproject.toml exists in the worktree, choose the uv environment path before running uv sync.

Default for a project-control-root layout:

<ProjectName>/.uv-envs/code

Run uv with an absolute UV_PROJECT_ENVIRONMENT pointing at that shared environment from both <ProjectName>/code/ and <ProjectName>/code-worktrees/*/:

cd <worktree-path>
UV_PROJECT_ENVIRONMENT=<absolute-project-root>/.uv-envs/code uv sync

Do not use a relative UV_PROJECT_ENVIRONMENT for cross-worktree sharing; uv resolves relative values against the active workspace root, which can still produce different environments for different worktrees.

Run commands from the active worktree with uv run .... Do not treat <absolute-project-root>/.uv-envs/code/bin/python as a branch selector; a shared editable install can point at the last synced worktree if Python is invoked directly outside uv.

If the branch changes dependencies, Python version, CUDA stack, or performs destructive package tests, create a named stage environment instead and record the reason:

UV_PROJECT_ENVIRONMENT=<absolute-project-root>/.uv-envs/code-<stage-or-lock-hash> uv sync

If uv sync fails, report the error but do not delete the worktree. The user may still want to inspect or fix the branch.

For paper worktrees, do not install TeX by default. Use the project's compile workflow: local static checks plus tex-fmt when available plus GitHub-linked Overleaf unless the user explicitly wants local TeX.

Step 9 - Write Worktree Memory

If the workspace has a research purpose, create or update:

<worktree>/.agent/worktree-status.md

Include:

• branch
• path
• created date
• parent branch
• purpose
• linked claims, experiments, risks, or reviewer issues
• expected difference from main branch
• for paper worktrees: target venue/version, template/style differences, source cleanup policy, and public/private source assumptions
• for paper worktrees: source visibility tier, audience, sync target, allowed/forbidden file policy, and cleanup gate
• for code worktrees: uv environment path and whether it uses the shared project-code env or an exception-specific stage env
• result/output paths
• exit condition: merge, continue, park, or kill
• next verification step

If project memory exists, also add a short pointer to:

• memory/component-index.yaml: known worktree path
• <component>/.agent/worktree-index.md: component-local active worktree rollup
• memory/source-visibility-board.md: source visibility tier and cleanup gate for paper worktrees or visible branches
• memory/action-board.md: next action for the worktree
• memory/current-status.md: only if this is the active focus
• memory/project-conventions.md: if this worktree introduces a new naming convention, branch policy, or worktree-scope rule that future agents must know, add it under worktree category

The root registry and component worktree index are the cross-worktree memory surfaces. Do not rely on one worktree's leaf status file to tell future agents what other sibling branches or paper versions exist.

Step 10 - Final Summary

Report:

Workspace created

Repo: <repo-root>
Branch: <branch-type>/<branch-name>
Worktree: <path or branch-only>
Evidence paths:
  <code worktree only: docs/results/, docs/reports/, docs/runs/>
Memory:
  .agent/worktree-status.md <created|skipped>

Next:
  cd <worktree-path>
  <code: run uv with UV_PROJECT_ENVIRONMENT=<absolute-project-root>/.uv-envs/code, then run/edit the planned experiment>
  <paper: run submit-paper checks and sync to Overleaf/GitHub if needed>

Error Handling

• Not a Git repo: stop and ask for the target repo.
• Dirty tree: ask whether to commit, stash, continue, or cancel.
• Branch exists: ask whether to use existing branch or choose a new name.
• Worktree path exists: ask whether to choose a new name or inspect existing path.
• Sandbox blocks Git metadata writes: treat as a permission issue and use safe-git-ops.
• UV sync fails: keep the worktree and report the environment issue.
• Paper compile unavailable locally: do not install TeX by default; route through Overleaf/GitHub.

Configuration File Template

If .worktree-links does not exist, offer to create:

# .worktree-links
#
# Symlinks to create in new worktrees.
# List paths relative to the code repo root.

# data/
# models/
# .env
# configs/local_settings.yaml

Final Sanity Check

• branch or worktree was created in the intended component repo
• worktree is not nested inside code/ or paper/ unless explicitly requested
• git worktree list shows the expected path
• code evidence paths exist for code worktrees
• paper version policy is recorded for paper worktrees
• paper source visibility policy is recorded for paper worktrees, especially Overleaf/coauthor-visible and public-source branches
• worktree memory records purpose and exit condition when relevant
• code worktree uv policy points at the shared project-code environment or records a specific exception
• project memory is updated only with durable pointers, not logs