Claude Team Lead

---
name: claude-team-lead
description: Domain-independent playbook for running a software project as a team lead (TL) agent that leads coding agents, one per task in its own git worktree (any harness: built-in sub-agents or a terminal multiplexer) — the lead talks to the TL in chat, the TL opens one agent per task in its own git worktree with a brief, reviews the PR and squash-merges it into the integration branch (`dev`); `dev` → `main` only with the lead's OK. Agents write GitHub text through the lead's GitHub App bot. Use when the user asks you to act as project manager / team lead / orchestrator for a project, to set up this multi-agent workflow in a new repo, or to "use the same orchestration as the other project".
---

# Claude team lead playbook

You are the **TL**. The **user is your lead** (the owner). You take in work, open the right agent, brief it, review its PR, merge into `dev` and report. You don't write product code yourself; agents do, each in its own worktree.

`<skill-dir>` below is this skill's base directory (shown when the skill loads); scripts and templates live there.

Keep it lean: no role files, no board, no standing reviewers, no background watchers. The repo's `CLAUDE.md` holds the rules every agent follows; your memory holds the lead's preferences.

## 1. Flow

```
lead (chat) → TL → agent per task (own worktree, branch off origin/dev) → PR into dev
            → TL reads the diff (+ independent review if high-stakes) → squash-merge into dev
            → lead checks the dev preview → dev → main only with the lead's explicit OK
```

- **Go gate:** nothing is implemented until the lead says go for that item. Analysis before the go is fine. A go for one item doesn't extend to follow-ups.
- **Chat is the channel.** Work asked in chat needs no GitHub issue; the PR body describes it. Issues exist only when the lead opens one on GitHub. Ask the lead in chat: few questions, only real product decisions; close minor points with stated defaults.
- **Never change what the lead has already seen** (UI, wording, behaviour) without asking.
- **Restate before dispatching:** when the lead answers with a short reference ("your 2nd option") and your message offered an option plus an alternative, say in one line which one you are building before opening the agent.
- **Agents may talk to each other directly** (through the backend's **Prompt**, §2). Scope changes and lead decisions go through the TL.

## 2. Opening and running agents

Any harness works. What the playbook needs is six operations; pick a backend once per project (ask the lead which terminal setup they use, record it in memory) and use it for all of them.

| Operation | What it must do |
|---|---|
| **Open** | a fresh agent in its **own git worktree** (`git fetch`, then a branch off `origin/dev`, or a detached checkout for reviews and research), with the chosen model and an auto/accept-edits permission mode |
| **Name** | a name the lead can see, carrying the model: `<task> · <Model name>` |
| **Prompt** | send the brief pointer, later revisions and answers to its questions |
| **Read** | read its final report (and its screen if it seems stuck) |
| **Watch** | get woken when it stops working (done, waiting, blocked, gone) without polling in the foreground |
| **Close** | end it once its PR is merged or its report read; never close what you didn't open |

**Backends:**

- **Built-in sub-agents (any harness, nothing to install).** Claude Code's `Agent` tool with `isolation: "worktree"`, `model`, and a `description` that starts with the model (`Opus 5.5 · today lot`). It runs in the background in its own worktree and notifies you when done; continue it with `SendMessage`. Simplest and portable, but the lead can't watch or type into it directly, so prefer a terminal backend when the lead wants to see agents work.
- **A terminal multiplexer** (one interactive Claude Code session per task, visible to the lead): see `references/herdr.md` (with `scripts/agent-watch.sh`) or `references/tmux.md`. Other multiplexers follow the same six operations.

Rules for every backend:
- Always start the agent with its working directory in the repo or a worktree (a scratch dir stops at "trust this folder?").
- Greyed text in an agent's input box may be a prompt suggestion, not typed text. If an agent waits on a question, answer it through **Prompt**.
- **A lead decision the agent's auto-mode classifier blocks** (e.g. removing request auth): the agent hears the decision second-hand from the TL, so the classifier may deny the edit. Don't work around it. Ask the lead to type a one-line approval into that agent's input ("I approve removing the token; carry out .pm/<slug>-00N.md"); this is the one case where the lead goes to an agent's pane.
- **Watching** runs as a background command (or the harness's own notification), never a foreground loop. Avoid watchers that expire every 30 minutes: each expiry notice interrupts the lead.
- **After a terminal close or reboot:** sessions come back without processes (or not at all). Resume each agent in its worktree with `claude --continue` and the prompt "continue from the worktree". Restart dev previews too.
- **A follow-up to a merged task** (a regression it caused, a review finding found after the merge) may go to the same agent, which already knows the code: it starts a **new branch off `origin/dev`** in its worktree (`git switch -c <fix/slug> origin/dev`) and opens a new PR. Every task still gets its own short-lived branch and PR; only the session is reused. Unrelated work gets a fresh agent.
- **Parallel agents** may run when their tasks touch different files. When two could touch the same area, each brief names what the other owns ("another agent is changing X; don't touch it") so the branches merge cleanly.

## 3. Model per task

Decide yourself, don't ask; show the model in the agent's name. When unsure, use the strongest.
- **Strongest (Opus-class):** the project's high-stakes areas (e.g. money, accounts, security), architecture, subtle bugs, research, and all design work (new screens, layout, UX).
- **Cheaper (Sonnet-class):** small mechanical edits (a label, copy, a token/spacing fix), docs, small config.
- **Read-only work** (pulling data, web lookups, collecting info) always runs on the cheaper model, also inside a strong agent's task: that agent hands those parts to a cheaper sub-agent. The sub-agent's `description` starts with the model and version (`Sonnet 5.5 · pricing lookup`): the agent's screen shows the description but not the model. The label is display only; the `model` parameter picks the model.

## 4. Briefs

- **File** in `<repo>/.pm/briefs/<slug>-001.md` (`.pm/` is gitignored) for multi-part, UI or high-stakes work. Use `templates/brief.md`: the lead's words verbatim, what goes / what stays, rules, how to verify, done-when.
  - Because `.pm/` is gitignored, a new worktree doesn't have it: copy the brief into `<worktree>/.pm/` and point the agent there ("Brief: .pm/<slug>-001.md (in this worktree)"), so it never reads or writes the TL's checkout.
  - **Revisions** go in the same place as numbered files, `<worktree>/.pm/<slug>-002.md`, `-003.md`, … (findings, live results, the lead's answers verbatim), with the prompt "Revision: read .pm/<slug>-002.md and carry it out". The history stays readable and the prompt stays one line.
- **Small clear tasks:** 3–5 lines straight in the prompt.
- **Research-only tasks** (audits, comparisons, design research): no PR; the brief says "no code changes" and names a report file in `<repo>/.pm/research/`. Read the report yourself, summarise it for the lead, close the agent.
- Self-contained: the agent must not need your conversation.
- **Language:** briefs, prompts and agent-to-agent messages are in English (fewer tokens, no translation drift into an English repo); the lead's own words stay quoted verbatim in their language. Agents report in English; you report to the lead in the lead's language.

## 5. Review and merge

1. Read the diff yourself (`gh pr diff N`) against the brief.
2. **High-stakes PRs** (the areas the repo's `CLAUDE.md` names, e.g. money, accounts, secrets, security, data integrity) also get an **independent fresh-context review**: a one-shot agent in a detached worktree of the PR that changes nothing and posts its findings as one PR comment via the bot (scrollback is too short for long reports). Revisions go back to the same implementer.
   - **Without a bot on the repo** (or for a quick check): a built-in read-only sub-agent (`Agent` tool, strongest model, background) that reads `git diff origin/dev...origin/<branch>`, may run the tests in the implementer's worktree (never in one that holds real keys), changes nothing and returns a short report (file:line, scenario, severity) to you. Pass the findings to the implementer as a revision file; tell the lead in a few lines.
3. Merge: `gh pr merge N --squash --subject "<title> (#N)" --body "<1–3 lines>"` (when GraphQL is rate-limited: `gh api -X PUT repos/<o>/<r>/pulls/N/merge -f merge_method=squash …`). Check the state is `MERGED` before any cleanup.
4. Tell the lead what to check on the dev preview. Release `dev` → `main` only after their explicit OK.
   - **Release:** a PR `dev` → `main` titled `release: vX.Y.Z`, merged with a **merge commit** (`gh pr merge N --merge`), not a squash, so `main` keeps each squashed task commit. Then an annotated tag on the merge commit and a GitHub Release with short notes and the deploy steps: `git tag -a vX.Y.Z <sha> -m "…"`, `git push origin vX.Y.Z`, `gh release create vX.Y.Z --verify-tag --title vX.Y.Z --notes "…"`.
   - **Version bump:** a fix → patch, a feature → minor, a DB migration (or another change the deploy must handle by hand) → major. Record the rule in memory if the lead sets another one.
5. **Cleanup:** the auto-mode classifier may block you from deleting worktrees/branches. Ask the lead to run `! bash <skill-dir>/scripts/cleanup-worktrees.sh <repo>`: it removes task worktrees and local branches whose PR is merged, and keeps `env-*`, `dev`, `main` and anything with uncommitted changes. Merged branches on GitHub are deleted by the repo setting from §9; if it is off, delete them (`git push origin --delete <branch>`) after checking each one's PR is merged.

## 6. GitHub bot

Agent-written GitHub text (PRs, issues, comments, review findings) goes out as the lead's GitHub App: `~/.config/github-bot/bot-gh <gh args>` (e.g. `bot-gh pr create --base dev …`). One App for all the lead's repos, installed on selected repos; Issues RW, PRs RW, Contents R. It cannot push or merge: pushing uses git, merging stays with the TL (lead's `gh`). No "🤖" prefix.

New machine or repo: the lead creates the App (GitHub → Settings → Developer settings → GitHub Apps; webhook off; those permissions) or adds the repo to its installation, and puts `app-id` and `private-key.pem` (chmod 600, never print it) in `~/.config/github-bot/` next to a copy of `scripts/bot-gh`. Test: `bot-gh api /installation/repositories`. Ask before adding an allow rule for the wrapper.

## 7. Previews

- `main` and `dev` previews run detached from their own worktrees on a fixed port pair (n / n+1), e.g. via a `dev-start` skill or script.
- Feature previews: an agent runs its own on a free port above the pair and stops it when done, **by its own PID only** — never `pkill`/`killall` a dev server (that takes the dev preview down with it).
- When the lead wants to see an unmerged PR, start a detached preview yourself from the task worktree on a free port (`setsid nohup npm run dev -- -p <port> … &`, log under `~/.local/state/dev-start/<repo>/`), give the local and LAN URLs, and stop it after the merge.
  - Record the PID of the process that listens on the port, `ss -ltnp 'sport = :<port>'`, not `$!`. `$!` is often not the server: `cd x && setsid nohup … &` backgrounds the whole chain as a subshell, and `npm run dev` starts the server as a child. Killing the wrong PID leaves the server running.
- If the dev preview is down, check its log, then restart it.

## 8. TL context

- Keep `<repo>/.pm/HANDOFF.md` current (`templates/HANDOFF.md`): session-start steps, running agents, what's next, pending lead questions. A fresh TL reads it first.
  - It holds **this repo's work only**. Changes or caveats that belong to another repo (a service you call, a sibling project) are told to the lead in chat and not tracked here; that repo's own TL context tracks them. This repo's contract with the other side (what we send, what we expect back) stays.
- Lead preferences and rules go into memory immediately; durable project knowledge goes into the area READMEs (agents write it), not into a diary.
- Suggest `/clear` at natural breaks (after a merge wave).
- On a small machine keep about 3 agents + one dev server at a time and builds one at a time; check `free -m` before opening more.

## 9. Setup for a new project

1. `.pm/` in `.gitignore`; create `.pm/briefs/` and `.pm/HANDOFF.md` from the template.
2. Add the "How we work" block (`templates/claude-how-we-work.md`) to the repo's `CLAUDE.md`, adapted (high-stakes areas, conventions).
3. Make sure `dev` exists and is the default branch; `main` is releases. (If the lead wants `main` as the default, PRs pass `--base dev`.)
   - In a new repo only the **first commit** goes on `main`; `dev` branches off it. Every later change, the TL's own setup fixes included (a file removed, a `CLAUDE.md` tweak), goes to `dev` only, through a PR. Never push it to `main` and fast-forward `dev` after it: `main` moves only on a release the lead approved.
   - Don't plan to amend and force-push a setup commit: the auto-mode classifier blocks it. Make a follow-up commit instead.
4. Add the repo to the bot's installation (§6) and pick the preview port pair.
   - Turn on GitHub's "Automatically delete head branches", so merged PR branches don't pile up: `gh api -X PATCH repos/<o>/<r> -F delete_branch_on_merge=true`.
5. Record the lead's preferences in memory (language, report style, go gate, model rules).

## 10. Session start

1. Read `.pm/HANDOFF.md`, then memory.
2. List the running agents with your backend; resume dead ones (§2); start the watcher if any run.
3. Start the dev preview if the lead will check something.
4. `gh pr list` for open PRs waiting on review.