repolab — Architecture Guide for AI Assistants

This file provides context for AI coding sessions working on the repolab codebase.

Make sure to always do work on a feature branch!

What repolab does

repolab is a CLI tool that creates isolated multi-repo lab environments for AI-assisted development. It uses git worktrees to check out multiple repos into a single named "lab" directory, populates it with a template (AGENTS.md, scratch dirs, etc.), and tracks state in a .repolab.yml file. Labs can be listed and torn down, which cleans up worktrees, branches, and the lab directory.

Package layout

repolab/
├── cmd/                    — Cobra CLI commands; thin orchestration only
│   ├── root.go             — root command, registers all subcommands
│   ├── init.go             — interactive first-run setup (huh forms)
│   ├── create.go, list.go, teardown.go, add_repo.go, remove_repo.go, repos.go
│   │                         — lab lifecycle commands, top-level (not nested under `lab`)
│   ├── template/           — template list / preview commands (nested, non-main-path)
│   └── config/             — config show / set / repo / repo-dir commands (nested, non-main-path)
├── internal/
│   ├── config/             — viper-backed TOML config at ~/.config/repolab/config.toml
│   ├── git/                — exec-based git worktree operations (no git library)
│   ├── lab/                — core lifecycle: Create, List, Teardown + .repolab.yml state
│   ├── pathutil/           — path normalization (~ expand, abs, symlink eval, dedup)
│   └── template/           — fs.FS-based template discovery and text/template rendering
└── internal/template/templates/
    ├── multi-repo/         — default template, embedded via go:embed
    └── ab-test/            — A/B comparison template with agent harness scripts

Key conventions

• Branch naming: git.FormatBranch renders branch_format; default {{.LabName}} (git.DefaultBranchFormat). Precedence: --branch > config.branch_format > default. Multi-env appends /<envName>. Result must pass ValidateBranchName.
• State file: <lab-dir>/.repolab.yml — read/written by internal/lab/state.go
• Template discovery: embedded FS first, then user's templates_dir config value
• Template rendering: all template files pass through text/template with Vars{LabName, Date, Repos[], Environments[], Custom{}}
• Meta file: .repolab.tpl.yml in a template dir is metadata only — never copied to the lab
• cmd/ boundary: cmd/ packages should not contain business logic; delegate to internal/
• No git library: exec-based git is intentional — simpler, always up to date with git features

Template format

Each template is a directory with:

• .repolab.tpl.yml — metadata (name, description, worktree_dir, optional extends, environments, variables)
• Other files rendered through text/template with Vars{LabName, Date, Repos[], Environments[], Custom{}}
• .gitkeep files create empty directories (not rendered through template engine)

Templates may declare custom variables (variables[]), collected at create (via --var, --yes defaults, or prompts) and rendered as {{.Custom.<Name>}}. A template whose variables block fails validation is silently dropped from discovery — the warning appears only on template list stderr. See docs/templates.md.

Config (~/.config/repolab/config.toml)

labs_dir = "~/Labs"
templates_dir = ""   # empty = embedded templates only

[[repos]]
path = "/path/to/repo"

Lab state (.repolab.yml)

name: lab-a
created_at: 2024-01-01T00:00:00Z
template: multi-repo
repos:
  - name: repo-a
    path: /abs/path/to/repo-a
    worktree_path: repos/repo-a   # relative to lab dir
    branch: repolab/lab-a/repo-a

Documenting features

A user-facing feature is not done until it is documented. Document it in the same change that ships it — before committing, and well before releasing.

If a change adds or alters any of these, it must update the docs in the same commit:

Rules:

• Write docs from observed behavior, not from code comments. Comments drift. Exercise the real binary end-to-end and document what it actually does. (The collectCustomVars docstring claimed a case errors when it silently returns an empty string — a doc written from that comment would have been wrong.)
• Document the sharp edges too. Silent drops, empty-value footguns, and validation failures that surface as an unrelated error are exactly what users hit first.
• Don't dress a limitation up as a design. If behavior is a known gap, say so and cite the tracking issue.
• Adding a feature to SPEC.md §I is not documentation. §I is the internal contract; README.md and docs/ are the user-facing surface. V16 and V19 exist because these drifted apart before — see §B.4.

Before opening a PR: go build ./... && go vet ./... && go test ./..., then re-read the diff and confirm every row above that applies has a matching doc change.

Testing approach

• internal/lab/state_test.go — YAML round-trip with t.TempDir()
• internal/template/template_test.go — readMeta and Render with testing/fstest.MapFS
• internal/git/worktree_test.go — pure string functions, no dependencies

Do not add tests for cmd/ packages — huh TUI interaction is not easily unit-testable.

Specs

SPEC.md at the repo root is the single spec-driven-development file (caveman-encoded: §G goal, §C constraints, §R research, §I interfaces, §V invariants, §T tasks, §B bugs). The old per-topic specs/ directory (completed.md, release-management.md, etc.) was retired when the project moved to this format — don't recreate it.

Build & run

go build -o repolab .
go test ./internal/...

./repolab init
./repolab template list
./repolab template preview multi-repo
./repolab create <name>
./repolab list
./repolab teardown <name>