Techcle Wiki

Plan

4 min read

TEC-25 — Workspace Skill: Per-Ticket Isolation via Git Worktrees

Package workspace lifecycle management as a Paperclip skill so any agent can create, use, and clean up isolated per-ticket workspaces.

Scope

Isolation applies to all repos an agent touches for a given ticket, including:

  • The root workspace repo (/workspace itself — a git repo)
  • Any sub-repos under repos/ (e.g. repos/domain-apis, repos/k8s-lab)

Most tickets touch the root workspace (config, .ai/projects/, Taskfile, skills). Some also touch one or more sub-repos. The skill handles both cases uniformly.

What the skill does

A new skill at skills/workspace-management/SKILL.md that agents invoke whenever they need to work on code in isolation. It wraps the existing builder:init / builder:cleanup Taskfile commands and adds Paperclip-aware lifecycle management.

Skill responsibilities

  1. Create workspace — Given a ticket identifier and target repo(s), create .builders/{ticket-identifier}/ with git worktrees. Root workspace is always worktreed to .builders/{id}/workspace/; sub-repos go to .builders/{id}/repos/{repo-name}/
  2. Set working directory — Agent cds into the worktree and works there; branch naming follows feature/{identifier}-{description} (e.g. feature/TEC-25-workspace-isolation)
  3. List active workspaces — Show which tickets have active worktrees and their branches
  4. Cleanup workspace — On issue completion/cancellation, remove worktrees and prune branches
  5. Guard rails — Refuse cleanup with uncommitted changes, warn on stale worktrees

Integration points

IntegrationHow
Paperclip issue lifecycleSkill reads PAPERCLIP_TASK_ID to derive workspace name from the issue identifier (e.g. TEC-25). Agents invoke cleanup when marking issues done/cancelled.
executionWorkspaceSettingsPaperclip issue field (currently null). When set on an issue, specifies which repos the agent needs. Agents read this to know what to worktree.
Existing Taskfile tasksSkill delegates to task builder:init, builder:cleanup, builder:list. Taskfile builder:init updated to accept BRANCH_NAME var (overrides default).
Multi-repo supportRoot workspace (.) is always included. Additional sub-repos specified as comma-separated list (e.g. REPOS=.,domain-apis,k8s-lab). Repos can be added to an existing workspace via builder:add-repos.
Branch namingConvention: feature/{identifier}-{description} (e.g. feature/TEC-25-workspace-isolation). Consistent across all repo worktrees for a given ticket.

Directory convention

.builders/ (keeping existing convention). Workspace name derived from issue identifier. Root workspace is always worktreed — this maintains the repo structure inside every builder workspace.

.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 (added at init or later)

Additional repos can be added to an existing workspace at any time via task builder:add-repos.

Skill structure

skills/workspace-management/
  SKILL.md
  references/
    worktree-ops.md

Trigger conditions

  • Agent needs to modify code in any repo (root or under repos/)
  • executionWorkspaceSettings is set on the current issue
  • Agent is about to create a feature branch or PR
  • Multiple agents working on same repo simultaneously

Skill procedures

Procedure 1: Setup workspace

  1. Read PAPERCLIP_TASK_ID, fetch issue to get identifier (e.g. TEC-25)
  2. Root workspace (.) is always included. Read executionWorkspaceSettings (or issue description) to determine additional sub-repos under repos/.
  3. Derive description slug from issue title (e.g. workspace-isolation)
  4. Run: task builder:init BUILDER_NAME=TEC-25 REPOS=.,domain-apis BRANCH_NAME=feature/TEC-25-workspace-isolation
  5. cd into .builders/TEC-25/workspace (or primary repo worktree)
  6. Comment on issue with workspace details

Procedure 2: Teardown workspace

  1. Verify all changes committed and pushed
  2. Run: task builder:cleanup BUILDER_NAME=TEC-25
  3. Comment on issue confirming cleanup

Procedure 3: List workspaces

  1. Run: task builder:list
  2. Cross-reference with active Paperclip issues
  3. Flag stale workspaces (issue done but worktree remains)

Implementation phases

Phase 1 — Skill file + Taskfile updates (1 task)

  • Write skills/workspace-management/SKILL.md with setup/teardown/list procedures
  • Update Taskfile builder:init to accept BRANCH_NAME var
  • Add root workspace worktree support (. in REPOS list creates worktree at .builders/{name}/workspace/)
  • Test with a real ticket

Phase 2 — Adapter integration (1 task)

  • Populate executionWorkspaceSettings on issues that need code changes
  • Modify agent adapter to auto-invoke workspace skill when settings present
  • Add workspace path to agent context/environment

Phase 3 — Stale workspace cleanup (1 task)

  • Periodic check for orphaned worktrees (issue done, worktree remains)
  • Add workspace:prune task to Taskfile
  • Skill warns when workspace is older than 7 days with no commits

Relationship to spec 0007

This plan supersedes the af spawn-centric approach in .ai/projects/infrastructure/multi-repo-builder-worktrees/spec.md. Key differences:

  • Skill-based (any agent can invoke) rather than tied to af spawn
  • Root workspace included as a first-class worktree target
  • Paperclip-native via executionWorkspaceSettings and issue lifecycle hooks
  • .builders/ directory convention (not .worktrees/)

Graph View