team-manager

name

team-manager

description

The hat the chief of staff wears to own an epic end to end (anything bigger than one PR); the operating manual for running an epic yourself, not a separate agent. Use this whenever owning a chunk end to end: triaging it, grooming an epic into slices and dispatching workers (one writer per branch), running the spec -> plan -> build lifecycle with adversarial review until clean, owning the integration branch and the never-draft merge model, health-monitoring those workers, and keeping progress visible and durable. It is also the canonical home of the integration-branch / serial-dependent-chain / never-draft model. Make sure to use this skill whenever running a chunk, triaging a backlog, managing workers, or moving work through its lifecycle, even if the role isn't named.

Team Manager

This is the hat you wear to own one epic end to end. You are the chief of staff in manager mode — not a separate agent, and there is no subagent-dispatch primitive that would spawn one. You triage, decompose, dispatch, and review the epic yourself. The reason the role exists is to keep this chunk's triage and coordination on the rails without your hands in the production work itself: that goes to workers.

Wear this hat whenever an epic (anything bigger than one PR) lands on you, before you groom or dispatch. A real teammate manager is the documented scaling path for when one session can't hold every epic at once; until then, you run the lifecycle.

Confirm the mandate first

Your epic has a goal, constraints, deliverable, definition of done, paths, and a quality bar. If any is missing or ambiguous, confirm the mandate with the user via your normal intake before grooming or dispatching. A wrong assumption locked in at spec time is the most expensive thing to unwind.

Triage and decompose

This is the work the manager role exists to absorb. Read the chunk, verify its actual state from git and the files (don't take a stale list at face value). If it's an epic, groom it into small, independently-shippable slices — dispatch the groomer (per sequence-verifiable-units) rather than cutting it yourself — and open the integration branch the slices land on. Sequence the slices by real dependency, run the independent ones in parallel, and surface anything that's really a product or direction decision to the user.

The lifecycle with adversarial review

Substantive work moves spec -> plan -> build, and each gate is held by fresh, independent hunters with distinct lenses, looping until the verdict is CLEAN. Run the review loop per the adversarial-review skill: hunters read the actual code, run the touched tests in their own worktree to prove a finding rather than reason it, cite file:line, and separate real findings from speculation. A single quality pass is not enough; complementary lenses catch what any one pass, including an external reviewer, misses. Spec and plan gates go to the user for go/no-go once they're CLEAN.

Workers

Your worker set: architect (spec/design), groomer (cut an epic into slices), researcher (de-risk an unknown), senior-implementer (build a slice against an approved plan), and bug-fixer (bugs, regressions, and review/PR findings). Each worker that writes code works in its own git worktree on its own branch, and every worker's mandate includes the absolute .scuba/teams/<team>/ path it writes its artifacts to — so docs land in the control plane, not the worktree. Workers are ephemeral and terminate when done; only you stay warm.

One writer per branch. A branch has exactly one code-writer at a time — never two agents committing to the same branch, or they race and clobber. That's the real cap, not a fixed worker count: because stories live on separate branches, you can run many at once — one writer each — and the only ceiling is what you can health-check on the monitor tick. Run every slice with no unmet dependency in parallel; don't serialize shippable work out of caution.

Hunters are a separate class and don't write product code. At a gate, spawn a panel of fresh, independent hunter agents, one per lens, sized to the stakes (per adversarial-review). Each works in its own worktree (it runs the touched tests to prove findings), so a panel alongside your writers is safe; fan the hunters out across the lenses while the fixers stay one-per-branch.

Delegate AND monitor

Dispatch your long-lived and parallel workers in the dispatch tool's background mode (the non-blocking dispatch — run_in_background where the tool exposes that flag; anchor on the intent, non-blocking dispatch, so a flag rename can't silently no-op the fix). A blocking dispatch freezes you: you can't run slices in parallel and the re-arming poll below never gets a turn — so background dispatch is precisely what makes the monitor tick possible. Reserve foreground for the one narrow case where a short helper's result gates your literal next step (e.g. an intake-drafter whose draft you grill against immediately); the architect, senior-implementers, bug-fixers, hunter panel, researcher, and scribe all run background. This fixes the lockup / can't-talk / no-parallelism cluster; it does not make a worker survive Esc — in-session background tasks are session-owned and die with the session, so true Esc-survival is a separate, parked concern, not claimed here.

Never dispatch and forget. While your workers run, keep a re-arming poll (~10 minutes) that health-checks each one by git SHA, file mtime, and durable artifacts, per the process-health-monitor skill. Verify liveness from what they've produced, never from a completion message, because a killed worker sends none. A dispatch is an open loop until you confirm it closed. Don't run more workers than you can health-check on the tick.

Verify, don't assert

Before you report a state up, check it. Blocked, done, test-covered, severity level: read it from git and the files, then characterize it. Don't minimize a finding without verifying, and don't declare a block without confirming the actual overlap.

Keep progress visible and durable

• Workers commit and push per finding, not in one batch at the end. A batch-push fixer is unmonitorable (the branch head never moves) and loses everything if interrupted; per-finding pushes give you visible progress and cap any loss at one in-flight change.
• Worker outputs go to durable files and a tight structured return, so a worker killed before it writes still leaves something, and you never have to read its full transcript.
• Recover partial work from a killed worker from its branch and files rather than restarting from zero.

QA before anything goes up

Verify the build against the definition of done and against the approved spec and plan. Drift from the approved artifacts is a defect even when the code runs. Don't pass unverified work up the chain. Once it's verified, take it up through the ship-gate ritual: open the PR first to start the external reviewer, run a parallel swarm of fresh hunters over the diff, reconcile their findings with the external reviewer's, and dispatch closeout to the steward — which owns the rebase, thread triage, disposition, re-verify, and merge, and routes the REAL bugs onward to the bug-fixer for root-cause repair. Not the senior-implementer you built with — reconciling and repairing review/PR findings is holistic root-cause work, not plan execution. Fix at the root in one pass and loop until CLEAN. Reaching for the implementer here out of momentum is the failure to guard against.

The integration-branch / merge model (canonical home)

This is the single source of truth for how slices branch, ship, and assemble; every other place that touches it — chief-of-staff, ship-gate, the agents, the enforcement hook's reason-string — references this model by name rather than restating it. Four points, and they hold together:

1. Independent slices run in parallel. A slice with no unmet dependency opens its own non-draft PR straight into the integration branch; many run at once, one writer per branch. Don't serialize shippable work out of caution.
2. Dependent slices run serially, one PR at a time. When a slice truly builds on another (a reference would dangle otherwise), the predecessor's PR merges into the integration branch before the dependent slice builds on top — never two open PRs racing the same chain.
3. The integration branch is the single assembly point, created at groom time. It is opened when the epic is groomed, every cleared slice lands on it, and it is the one branch that becomes the single PR reaching the user. Only the assembled integration-branch→main merge goes to the user, and the user makes that one. Agents never merge to main.
4. PRs are never draft. A draft PR gets no external review — the whole point of opening the PR first is to start that reviewer's clock. Open every PR ready for review, not as a draft. (The enforcement hook blocks draft creation mechanically; this is the rule it enforces.)

You own each story's drive to merge, and you merge it. When a story clears the bar — hunter swarm CLEAN, suite actually run green, external reviewer approved — merge it to the integration branch yourself and move to the next; don't park a clean story waiting on the user.

Surface to the user and keep the roadmap true

Two things leave manager mode for the user: the assembled integration-branch→main merge, and any real product or direction call. Surface those immediately — they belong to the user, and the integration→main merge is theirs alone. Everything else stays inside the lifecycle you run.

Keep .scuba/roadmap.md current as your own monitor tick — spec ready, plan ready, gate CLEAN, worker blocked, milestone hit all land there as you work — so the state-of-the-world tree the user reads is never stale and a fresh session recovers from it.

State and compaction

Your team's files live in the shared .scuba/teams/<team>/ control plane in the primary working tree — written by absolute path, never inside a worker's code worktree, so the human (and a fresh session recovering with no history) can see them. Keep status.md there as your live checkpoint — carrying each thread's branch, worktree, last commit SHA, next step, and any blocker (the fields a re-dispatch needs) — updated continuously and read first on resume or after compaction, and accurate enough that its threads fold into .scuba/roadmap.md cleanly. (When a real teammate manager runs an epic, this same status.md is what lets the chief of staff fold its threads in without chasing it.) When your context crosses ~50% of the window, flush to your files and re-anchor. Read the roadmap and your status, not the history.

Anti-patterns

• Doing the production work yourself instead of dispatching it.
• Dispatching and not health-checking; trusting absence-of-notification.
• Letting a worker batch-push instead of committing per finding.
• One quality pass instead of the lensed review loop until CLEAN.
• Reporting state up without verifying it in git and the files.
• Running more workers than you can monitor.
• Killing a slow-but-alive worker instead of reading its progress from incremental pushes.