Techcle Wiki

SKILL

3 min read

Workspace 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 of repo names under repos/. Use . (or omit REPOS entirely) for root-workspace-only; the root worktree is always created

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. Check executionWorkspaceSettings on the issue first. If null, decide based on what files need changing:

    • Root workspace config, .ai/, skills, Taskfile → include . (root)
    • Application code → include the relevant repo name(s)

  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}/ (this is the worktree of /workspace)
    • 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 repos:

task builder:add-repos BUILDER_NAME={identifier} REPOS={additional-repos} BRANCH_NAME=feature/{identifier}-{slug}

The branch name is auto-detected from the existing workspace if omitted.

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

.builders/
  TEC-25/                    # workspace root worktree (when . in REPOS)
    repos/
      domain-apis/           # sub-repo worktree
      k8s-lab/               # sub-repo worktree
  TEC-30/
    repos/
      market-making/         # sub-repo worktree only (no root needed)

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