Techcle Wiki

Spec

4 min read

0007 - Agent Farm: Multi-Repo Builder Worktrees

Summary

Enable af spawn to create isolated git worktrees within sub-repositories, allowing multiple builders to work on the same repo in parallel without conflicts.

Problem Statement

The codev workspace is a multi-repo workspace with 8 independent git repositories under repos/. The current agent-farm worktree system creates worktrees at the workspace level, but this doesn’t isolate work within sub-repositories:

codev/                          ← worktree created here
└── repos/
    ├── k8s-lab/.git            ← NOT isolated - shared by all builders
    ├── domain-apis/.git        ← NOT isolated
    └── ...

When multiple builders spawn, they all share the same sub-repo checkouts, leading to:

  • File conflicts when editing the same files
  • Branch confusion (all builders see the same branch)
  • Uncommitted changes from one builder visible to others

Goals

  1. Isolated sub-repo worktrees - Each builder gets its own worktrees of target sub-repos
  2. Multi-repo support - A builder can modify one or more sub-repos as needed
  3. Target repo specification - Clear mechanism to identify which repos a builder will modify
  4. Parallel builders - Multiple builders can work on the same repo simultaneously without conflicts
  5. Read access to all repos - Builders can read any repo for reference, write only to specified targets
  6. Clean PR workflow - Builder creates PRs against sub-repos, not the workspace
  7. Cleanup integration - af cleanup removes all builder worktrees in one operation

Non-Goals

  1. Workspace-level changes - Builders don’t modify workspace-level files (specs, plans, etc.)
  2. Submodule/subtree conversion - Not restructuring the repos/ directory
  3. Atomic cross-repo PRs - PRs that must merge together require manual coordination

Technical Approach

Worktree Location

Create worktrees in a .worktrees/ directory at workspace root, organized by repo:

codev/
├── .worktrees/
│   ├── k8s-lab/
│   │   ├── builder-0007-ingress/     ← worktree for builder 0007
│   │   └── builder-0008-storage/     ← worktree for builder 0008
│   └── domain-apis/
│       └── builder-0009-api/
└── repos/
    ├── k8s-lab/                      ← main checkout (for architect)
    └── domain-apis/

Target Repo Identification

Three options, in priority order:

  1. Explicit --repo flag (highest priority):

    af spawn -p 0007 --repo k8s-lab

  2. Spec metadata - Add repo: field to spec YAML header:

    # In spec file
repo: k8s-lab

  3. Infer from tags - Use first tag matching a repo name:

    tags: [k8s-lab, ingress, security]  # → targets repos/k8s-lab

If no repo can be determined, af spawn should error with a clear message.

Spawn Flow

af spawn -p 0007 --repo k8s-lab

1. Validate repos/k8s-lab exists and is a git repo
2. Create branch: git -C repos/k8s-lab branch builder/0007-feature
3. Create worktree: git -C repos/k8s-lab worktree add ../../.worktrees/k8s-lab/builder-0007-feature builder/0007-feature
4. Start builder in .worktrees/k8s-lab/builder-0007-feature/
5. Builder creates PR against repos/k8s-lab (not workspace)

Cleanup Flow

af cleanup -p 0007

1. Find worktree location from builder record
2. Remove worktree: git -C repos/k8s-lab worktree remove ../../.worktrees/k8s-lab/builder-0007-feature
3. Delete branch if merged: git -C repos/k8s-lab branch -d builder/0007-feature
4. Remove directory if empty

Builder Context

The builder’s working directory is the sub-repo worktree. The builder:

  • Only sees/modifies files in that repo
  • Creates commits on its builder branch
  • Creates PR against the sub-repo’s main branch
  • Has no access to workspace-level files (specs, plans are read-only context)

Database Schema Updates

The builders table needs:

  • target_repo - which sub-repo this builder targets (e.g., “k8s-lab”)
  • worktree_path - full path to the worktree

Architect Coordination

The architect role prompt should be updated to:

  1. Specify target repo when spawning builders
  2. Track which repos have active builders (via af status)
  3. Ensure specs/plans are committed before spawn (builder can’t see uncommitted workspace files)

Constraints

  1. One repo per builder - Simplifies worktree management significantly
  2. Specs/plans in workspace - Builder receives these as read-only context, doesn’t modify them
  3. Sub-repo PRs only - Builder PRs go to the sub-repo, not to the workspace repo

Success Criteria

  1. af spawn -p XXXX --repo k8s-lab creates worktree in .worktrees/k8s-lab/
  2. Two builders can work on repos/k8s-lab simultaneously without conflicts
  3. af status shows target repo for each builder
  4. af cleanup removes worktrees correctly
  5. Builder PRs target the correct sub-repo

Implementation Phases

Phase 1: Core Worktree Support

  • Add --repo flag to af spawn
  • Implement sub-repo worktree creation
  • Update builder launch to use worktree path
  • Update af status to show target repo

Phase 2: Cleanup and Polish

  • Update af cleanup for sub-repo worktrees
  • Add repo inference from spec tags
  • Error handling for missing/invalid repos

Phase 3: Prompt Updates

  • Update architect role with multi-repo guidance
  • Update builder role to understand single-repo scope
  • Document multi-repo workflow

Open Questions

  1. Should the builder have read access to other repos (for reference), or strictly isolated?
  2. How to handle workspace-level tasks (updating projectlist.md, etc.) - architect only?
  3. Should af spawn without --repo fall back to workspace worktree (current behavior)?

Graph View

Backlinks