team-lead-efficiency

name	team-lead-efficiency
description	Build team lead efficiency rules: limit sub-agents, polling discipline, no redundant re-work, parallel task launching.

Team Lead Efficiency

Rules for the lead agent when coordinating sub-agents to minimize waste and maximize throughput.

Task Scoping

Right-Size the Work

• 2-3 teammates is the sweet spot for most features. More than 3 increases coordination overhead without proportional speedup.
• Each teammate task should take 5-30 minutes. If a task takes over an hour, it's too large — break it up.
• If a task would touch fewer than 3 files, the lead should do it directly instead of delegating.

Non-Overlapping Ownership

Every file must have exactly ONE owner for a given phase:

Bad:

Agent A: Implement product service (touches product model, router, UI)
Agent B: Implement order service (also touches product model for inventory)

Good:

Agent A: Implement product service (owns product.service, product.router)
Agent B: Implement order service (owns order.service, order.router)
Lead: Handles shared code (product model changes for inventory) after both complete

The lead handles shared/cross-cutting code after teammates return — not in parallel.

Clear Boundaries in the Delegation Prompt

Every delegation must include:

1. Exact files to create or modify (not "implement the feature").
2. Read-only context files — schema, types, design docs the agent should reference but NOT modify.
3. Interface contracts — what inputs/outputs must match.
4. What NOT to do — explicit exclusions prevent scope creep.

Polling Discipline

Do Not Busy-Wait on Teammates

After launching sub-agents, the lead should:

1. Launch all independent agents at once (parallel, not sequential).
2. Work on non-overlapping tasks while waiting (documentation, tests, review plans).
3. Check status periodically — not continuously. Polling once per minute is sufficient.
4. Never re-do teammate work. If a teammate is slow, wait or stop them — don't duplicate their output.

When to Stop a Teammate

Stop a running teammate if:

• Its task is no longer needed (requirements changed).
• The lead has already completed the work (this means the task was mis-delegated).
• The agent has been running over 2x the expected duration with no progress.

Don't stop a teammate just because it's slower than expected — context switching is expensive.

Integration Sequence

After all teammates return:

1. Read each teammate's output before making changes.
2. Run type checker across the full codebase (catches cross-agent incompatibilities).
3. Run the dev server (catches runtime issues).
4. Fix integration issues — the lead resolves conflicts, not another sub-agent.
5. Report results to user — summarize what each agent delivered, any issues found, and what was fixed.

Opus 4.7 Behavioral Changes

When the Team Lead is running on Opus 4.7, the defaults shift in ways that affect delegation:

• Spawns fewer subagents by default. Opus 4.7 prefers to do work inline rather than fan out — it will often handle tasks directly that Opus 4.6 would have delegated.
• Calls tools less often. More reasoning per turn, fewer redundant reads or repeated greps.
• Calibrates response length to task complexity. Won't over-explain a simple fix, and won't pad short answers.

These defaults are usually what you want. When they aren't, be explicit in the prompt:

If you need…	Say so explicitly
More subagents	"Use subagents to investigate X and Y in parallel."
More tool use	"Read files A, B, C and compare their interfaces before proposing the change."
Verbose output	"Provide a detailed analysis with code examples and line-number citations."
A specific decomposition	"Split this into three tasks: schema, API, UI. Delegate each to its own subagent."

Do not assume Opus 4.7 will infer the same delegation defaults Opus 4.6 used. If you've been running with xhigh effort and noticing thinner output than you expected, the cause is usually the model right-sizing — not the effort level.

Cycle-Transition Handoff (Recommend, Don't Ask)

When a session starts after a cycle has shipped — or when /cooldown has just finished writing its report — the Team Lead's first message must lead with a concrete recommendation, not an open-ended "What's next?".

The rule

If the answer to a candidate question is already in the project's documentation — CLAUDE.md, AGENTS.md, ROADMAP.md (when the consuming project ships one), or specs/pitches/*/pitch.md frontmatter — recommend, don't ask. Authorizing the next bet stays explicit (the user still runs /bet and /cycle-start); the change is how you ask, not whether you ask.

Procedure at session start after a shipped cycle

1. Read the cooldown report. Look for specs/retros/cooldown-after-<NN>.md matching the most recent cycle-<NN>.md. If present, the cooldown-report agent has already named the recommended next bet — surface its Next-bet recommendation line verbatim.

2. Otherwise, derive it. Read ROADMAP.md if present at the consuming project's repo root (code-copilot-team itself does not ship one — this is for downstream projects). If absent, scan specs/pitches/*/pitch.md for bet_status: shaped and rank by appetite-fit + scope clarity + circuit-breaker concreteness.

3. Lead with the recommendation, not a question:

   Bad — open-ended deferral when the roadmap already has the answer:

   Cycle 0 shipped. PR merged. Cycle 1 (foundation) is shaped.
   What's next?
   

   Good — concrete recommendation with the exact commands:

   Cycle 0 shipped. PR merged. Cycle 1 (foundation) is shaped and is the
   next bet per ROADMAP. Recommend `/bet 0001-foundation` followed by
   `/cycle-start 0001-foundation`. Confirm?
   

4. Fall back to listing candidates only when genuinely ambiguous. If multiple shaped pitches tie with no clear ordering, OR if no shaped pitches exist, then a list-and-ask prompt is appropriate. Default to recommendation; ask only when you must.

Why this matters

The agent labelling cycle 1 as "the natural next bet" in its own state table and then asking the user "What's next?" anyway is the failure mode issue #25 documents. The answer is in the question. It forces a round-trip the user shouldn't have to make, trains the user to ignore the agent's own reasoning, and slows momentum at exactly the moment Shape-Up wants the next bet locked.

See also: claude_code/.claude/agents/cooldown-report.md (the agent that emits the recommendation), claude_code/.claude/commands/cooldown.md (the command that surfaces it), and docs/shape-up-workflow.md § "Cycle-transition handoff".

Anti-Patterns From Real Projects

Anti-Pattern	What Happened	Prevention
434 TaskList polls	Lead busy-waited on 3 teammates, wasting tokens	Poll once per minute; work on other tasks while waiting
Lead duplicated teammate work	Lead started implementing what a teammate was assigned	Never overlap — if you assigned it, wait for it
Teammate stopped early	Lead stopped a slow teammate and redid the work	Only stop if the work is no longer needed
Too many teammates	3 teammates for a task where 2 would suffice	Start with 2; add a 3rd only if there's a genuinely independent third domain
Vague delegation	"Implement the frontend pages" with no file list	Always specify exact files and acceptance criteria
"What's next?" after a shipped cycle	Lead asked open-endedly when the roadmap had already named the next bet	Surface the cooldown-report's Next-bet recommendation verbatim; ask only on genuine ambiguity (issue #25)