Techcle Wiki

SKILL

3 min read

Workspace Management Skill

Manage per-ticket isolated workspaces using git worktrees in .builders/.

When to use

  • Before modifying code in any repo (root or repos/*) for a Paperclip issue
  • When multiple agents need to work on different issues simultaneously
  • When cleaning up after an issue is completed or cancelled

Setup workspace

Create an isolated workspace for a Paperclip issue.

Inputs

  • PAPERCLIP_TASK_ID (env var) — the issue being worked on
  • Issue identifier (e.g. TEC-25) — derived from the issue API
  • Target repos — comma-separated list. Use . for root workspace, repo names for sub-repos under repos/

Procedure

  1. Fetch the issue to get its identifier and title:

    GET /api/issues/{PAPERCLIP_TASK_ID}

  2. Derive the branch name from the identifier and a slug of the title:

    feature/{identifier}-{slug}

    Example: feature/TEC-25-workspace-isolation

  3. Determine which repos are needed. The root workspace (.) is always included. Check executionWorkspaceSettings on the issue for additional sub-repos. If null, decide based on what files need changing:

    • Application code → include the relevant repo name(s) in addition to .

  4. Run the Taskfile command:

    task builder:init BUILDER_NAME={identifier} REPOS={repo-list} BRANCH_NAME=feature/{identifier}-{slug}

    Example:

    task builder:init BUILDER_NAME=TEC-25 REPOS=.,domain-apis BRANCH_NAME=feature/TEC-25-workspace-isolation

  5. Work inside the worktree:

    • Root workspace: .builders/{identifier}/workspace/ (always created)
    • Sub-repos: .builders/{identifier}/repos/{repo-name}/

  6. Comment on the issue with workspace details.

Notes

  • The BUILDER_NAME should match the issue identifier (e.g. TEC-25)
  • If BRANCH_NAME is omitted, it defaults to builder/{BUILDER_NAME}
  • All repos in a workspace share the same branch name for consistency

Add repos to existing workspace

If you discover mid-task that you need additional sub-repos that weren’t included at setup:

task builder:add-repos BUILDER_NAME={identifier} REPOS={additional-repos} BRANCH_NAME=feature/{identifier}-{slug}
  • Only specify the new repos to add (not repos already in the workspace)
  • The branch name is auto-detected from the existing workspace if omitted
  • New repos are worktreed to .builders/{identifier}/repos/{repo-name}/ using the same branch name as the existing workspace

List workspaces

task builder:list

Shows all active builder workspaces, their branches, and repo counts.

Teardown workspace

Clean up after an issue is completed or cancelled.

Procedure

  1. Ensure all changes are committed and pushed in every worktree
  2. Run cleanup: 
    task builder:cleanup BUILDER_NAME={identifier}
  3. Comment on the issue confirming workspace cleanup

Safety

  • Cleanup refuses to proceed if there are uncommitted changes in any worktree
  • Branches are deleted locally during cleanup — ensure they’ve been merged or pushed first

Directory convention

The root workspace repo is always worktreed to .builders/{id}/workspace/. Sub-repos go under .builders/{id}/repos/{repo-name}/.

.builders/
  TEC-25/
    workspace/               # root workspace worktree (always created)
    repos/
      domain-apis/           # sub-repo worktree
      k8s-lab/               # sub-repo worktree
  TEC-30/
    workspace/               # root workspace worktree (always created)
    repos/
      market-making/         # sub-repo worktree

Branch naming convention

All branches follow: feature/{identifier}-{description-slug}

Examples:

  • feature/TEC-25-workspace-isolation
  • feature/TEC-30-api-rate-limiting

Integration with Paperclip

  • Issue identifier → workspace name (.builders/TEC-25/)
  • Issue title → branch description slug
  • executionWorkspaceSettings → which repos to worktree (future)
  • Issue completion → trigger workspace teardown

Graph View