Team Lead

Coordinate a cluster of tickets within a single domain. Detect dependencies, inject domain context, sequence properly, and launch pipelines.

This skill is an internal orchestration component — it is only called by ticket-swarm, never directly by the user.

Responsibility boundaries

A team lead is a coordinator, not a new agent role. It groups, sequences, and injects context, then delegates to the same pipeline agents.

Input contract

The team lead receives from ticket-swarm:

• Cluster: A list of enriched tickets (from ticket-pickup Steps 2-4), each with:
  • Ticket key, summary, priority, complexity classification
  • ticket_complexity: simple | medium | complex per ticket
  • Codebase references (file paths found during enrichment)
  • Jira linked issues (blockers, duplicates, related)
• Domain tag: backend, frontend, infra, or unknown
• Execution flags: swarm_mode: true, execution_mode: autonomous, and unbounded: true when the swarm was invoked with it
• Parent story key (optional): If these tickets are sub-tasks of a Story, the parent key for Jira comment context

Step 1: Analyze dependencies within the cluster

Examine the enriched ticket data to detect relationships:

File-level dependencies

Compare codebase references across tickets in the cluster. If two tickets reference the same file:

• They must not run in parallel (merge conflict risk)
• Sequence them: the simpler ticket runs first (fewer changes = easier base for the next ticket)
• Mark with: [sequenced: shared file {path}]

Jira link dependencies

Check linked issues between tickets in the cluster:

• "Blocks" links: If ticket A blocks ticket B, A must complete first
• "Relates to" links: Advisory only — note the relationship but don't force sequencing unless files also overlap
• "Duplicate" links: Flag to the swarm orchestrator — duplicates should not both be implemented

Logical ordering

For sub-tasks from a Story decomposition, infer logical dependencies even if files don't overlap:

• Database schema changes before API changes
• API changes before frontend changes
• Shared libraries/interfaces before consumers
• Tests that validate integration after the components they test

Build the dependency graph

Produce a sequencing plan:

Cluster: Backend (4 tickets)

  Wave 1 (parallel):
    PROJ-1003 (Simple) — DB migration, no dependencies
    PROJ-1007 (Simple) — Config change, independent

  Wave 2 (parallel, depends on Wave 1):
    PROJ-1001 (Medium) — API update, depends on PROJ-1003 [shared: app/lib/MC/Billing.php]
    PROJ-1009 (Simple) — Error handler fix, independent

  Wave 3 (sequential, depends on Wave 2):
    PROJ-1002 (Medium) — Service integration, depends on PROJ-1001 [Blocks link]

If no dependencies exist, all tickets can run in parallel (single wave).

Step 2: Inject domain context

Based on the domain tag, prepare domain-specific context to pass to each pipeline. This context supplements the enriched ticket brief.

Backend domain context

Domain: Backend (PHP / Avesta MVC)

Conventions:
- Controllers in app/controllers/, business logic in app/lib/MC/
- Models in app/models/, gRPC via Autolyse in app/lib/Autolyse/
- Tests in tests_phpunit/ using Phake for mocking
- snake_case variables, camelCase methods, PascalCase classes
- No abstract classes — favor composition
- No named arrays for structured data — always use a class
- Alphabetically sort imports, methods, and properties

Validation:
- PHPStan and Phan must pass after changes
- Run devenv test for PHPUnit tests

Security:
- XSS protection for any view/template changes
- CSRF protection for controller actions and Autolyse services
- SQL injection protection for any database queries

Frontend domain context

Domain: Frontend (React / TypeScript)

Conventions:
- Components in web/js/src/
- Routes in web/js/src/Main/routes/
- Always use IDS/MCDS design tokens — no hardcoded colors, spacing, or typography
- Check Figma alignment when available
- Invoke the frontend-design skill for any visual changes

Validation:
- ESLint and TypeScript checks must pass
- Jest tests for components

Infra / Cross-Boundary domain context

Domain: Infrastructure / Cross-Boundary

Conventions:
- Proto changes go in proto/, never edit app/lib-grpc/ directly
- gRPC code is auto-generated from protos
- Database migrations are Tuesdays only — if a migration is needed, flag prominently
- Feature flags in config/flags.ini, always start at enabled = 0.00
- Observability: traces around entry points, logging context through call chains

Special rules:
- Changes that span backend + frontend must coordinate commit ordering
- Proto changes require regeneration step before dependent code compiles

Unknown domain

No additional context injected. The ticket's own enrichment data is sufficient.

Swarm context accumulator

The team lead maintains a shared context object that accumulates results across waves. This gives downstream agents awareness of what upstream agents built, beyond just the files on disk.

Path note: when Step 3's workflow path succeeds, team-lead-waves maintains this accumulator internally (same injection, same size limits) — the prose procedure below governs the legacy fallback path only.

Initialize the context as empty before Wave 1.

After each wave completes, append a brief summary:

Wave 1 results:
  PROJ-1003: Created app/lib/MC/Billing/AccountId.php (new value object)
             Modified app/models/Invoice.php (added billing_account_id column)
  PROJ-1007: Modified config/flags.ini (added mc_billing_multi_account flag)

Inject the accumulated context into each subsequent wave's pipeline agents alongside the domain context: "Prior wave context: {accumulated}"

This context is ephemeral — it lives only for the duration of the swarm run and is not persisted to agent memory. It is included in the run log for swarm-retro analysis.

Accumulator size limits:

• Keep only the last 3 wave summaries in full detail
• For earlier waves: condense to a single line per ticket (key, files changed, pass/fail)
• Max total accumulator size: ~200 lines
• If exceeded: drop the oldest wave details, keeping only the condensed single-line entries

Step 3: Execute waves — invoke the team-lead-waves workflow

Wave execution runs through the saved team-lead-waves workflow (.claude/workflows/team-lead-waves.js). The workflow owns the execution topology — a sequential outer loop over waves, parallel() over each wave's tickets — while this skill keeps ownership of building the dependency graph (the Step 1 sequencing rules) and injecting domain context (Step 2). The seam follows the same three-part contract as code-auditor/SKILL.md Step 2 (the proven canary pattern): invoke, validate, fall back.

1. Invoke. Invoke the team-lead-waves workflow, passing a single JSON object through the Workflow tool's args:
   • waves — the Step 1 sequencing plan in the swarm-context shape: an array of { index, tickets: [Jira keys], parallel }. The workflow executes this plan as given; it never re-sequences.
   • domain — the cluster's domain tag (backend / frontend / infra / unknown)
   • sequencing_reasons — one entry per Step 1 ordering decision
   • briefs — a map from ticket key to that ticket's full pipeline brief text: the enriched ticket brief, the Step 2 domain context, the branch name (and base branch for sequenced tickets), and ticket_complexity. The workflow passes each brief verbatim to that ticket's pipeline agent.
   • unbounded — true when the swarm was invoked with it; omit otherwise. The workflow adds it to each pipeline's flags.

2. Validate. Check the workflow's return against .claude/workflows/schemas/swarm-context.json. The four required fields must be present and well-typed:

   • waves (the executed wave plan, echoed back)
   • sequencing_reasons (array of strings)
   • domain (enum backend / frontend / infra / unknown)
   • blocked (Jira keys of tickets that did not complete; empty array when every ticket succeeded)

   The optional advisory array may also be present. Unlike blocked, its items are objects, not bare keys: { "ticket": "PROJ-1234", "verdict": "one-line ruling" }, one per ticket whose pipeline ended with a correct no-code answer. Do not require it; treat absence as empty. Do not reject a payload for carrying it.

   Validate only those fields. The workflow returns no prose — its per-wave narration goes to the run journal — so do not require or parse any text alongside the object. A malformed args payload makes the workflow return null fields that fail this validation by design, engaging the fallback below.

3. Fall back. If the invocation errors, returns nothing, or the return fails validation, run the legacy prose wave execution (labelled fallback block below) and drive the waves the old way. State plainly in the output that the fallback path ran, e.g. "Workflow invocation unavailable — waves executed via the prose path." The cluster gets processed either way; the only cost of a failed seam is a line of text.

Journal diagnostic — check before declaring failure. If the return seems empty, consult the workflow run's journal.jsonl before concluding the invocation failed. A workflow that ran correctly but whose return did not surface looks identical to one that never ran; the journal distinguishes them. Record what the journal showed alongside the fallback notice.

Fallback occurrences must be visible, not silent. If the fallback notice appears on every run, the workflow seam is broken and should be treated as unproven rather than as a working feature — surface that pattern to ticket-swarm and the user instead of quietly absorbing it.

Concurrency ceiling. parallel() caps at 16 concurrent agents (1000 per run). A wave wider than 16 queues rather than erroring — the workflow logs each wave's width so a 40-ticket wave reads as queued, not mysteriously slow. The same practical ceiling applies to the legacy path's Agent-tool fan-out: log the wave width before launching.

Interpreting the validated return:

• The workflow maintains the swarm context accumulator internally (injecting prior-wave results into each subsequent wave's pipeline prompts, with the same condensation limits as the accumulator section below), so on this path there is no accumulator to maintain in prose.
• Per-wave progress narration lands in the workflow run's journal.jsonl; mine it for the per-wave detail lines when reporting to ticket-swarm.
• For each ticket in blocked, run Step 3.5 smart failure analysis before escalating. Tickets in advisory are not blocked: skip failure analysis, do not retry, and report them under Advisory. Any re-run this produces is a prose-orchestrated Agent call (see Truncation handling below).
• Feed the returned object into the Step 4 cluster report.

Fallback: legacy prose wave execution

Execute the sequencing plan from Step 1, wave by wave:

For each wave:

1. Launch one pipeline per ticket in the wave. For each ticket, invoke ticket-pickup with:
   • The enriched ticket brief
   • Domain context from Step 2
   • Swarm context from the accumulator (prior wave results)
   • Jira ticket key
   • Branch name (determined by ticket-swarm)
   • swarm_mode: true, execution_mode: autonomous (plus unbounded: true if received)
   • ticket_complexity from the ticket's classification (determines whether Cyrus auto-triggers Scout, code auditor, or Ranger on completion)
   • For independent tickets: branch is created by ticket-swarm (via newbranch or fallback) from the latest default branch
   • For sequenced tickets: the prior ticket's branch as the base (instead of the default branch)
2. Wait for all pipelines in the wave to complete.
3. Collect results from each pipeline:
   • Files changed, tests written, coverage metrics
   • Pass/fail status, blockers encountered
   • Reviewer results (Scout or Ranger depending on complexity)
4. Update the swarm context accumulator with this wave's results (files created/modified, classes/interfaces established).
5. If any pipeline in the wave fails or reports a blocker: Run smart failure analysis (Step 3.5) before escalating.
6. Report wave completion to ticket-swarm:

   [Backend Lead] Wave 1 complete: 2/2 succeeded
   
     PROJ-1001: API update (Medium) — 2 files, 8 tests, coverage 90%, Auditor->Scout: clean
     PROJ-1007: Config change — 1 file, 2 tests, coverage 88%, Scout: clean
   
   Proceeding to Wave 2...

7. Proceed to the next wave.

Every pipeline invocation on this path is a prose-orchestrated Agent call: verify the <<task-complete>> sentinel in each returned response and emit agent_truncated on suspected truncation (see Truncation handling below).

Step 3.5: Smart failure analysis

When a pipeline in a wave reports a blocker, auto-analyze before escalating to the user. This reduces unnecessary user interruptions.

This applies on both Step 3 paths: on the workflow path, run it for each ticket in the returned blocked array (mining the run journal for the failure detail); on the legacy path, when a pipeline reports a blocker mid-wave. Any retry or re-run this step launches is a prose-orchestrated Agent call.

Flaky test detection

Check if the failing test meets flaky test criteria:

• The test file was not modified by this pipeline (failure in pre-existing test code)
• The test name matches known flaky patterns from agent memory (~/.claude/agent-memory/ticket-swarm/classification-heuristics.md, "Known flaky tests" section)
• The failure message suggests timing/network issues (timeout, connection refused, intermittent assertion)

If flaky test criteria are met:

• Auto-retry once without user intervention
• Log as [auto-retry: suspected flaky test — {test-name}]
• If retry succeeds: proceed normally, note in run log
• If retry fails again: escalate as a real failure

Cross-ticket dependency failure

Check if the error references code from another ticket in the cluster:

• The error message mentions a class, method, or file that another ticket in this cluster created or modified (from the swarm context accumulator)
• The error is a "class not found", "method not found", "undefined function", or import failure

If cross-ticket dependency is detected:

• Auto-resequence: move the failed ticket to a later wave, after the ticket that provides the dependency completes
• Log as [auto-resequence: dependency on {other-ticket} — {symbol}]
• Do not count this as a retry — it's a sequencing correction

Real failure

If neither flaky test nor cross-ticket dependency applies:

• Surface to the user with failure analysis context:

  {ticket} [BLOCKED] — Test failure (real)
    Failing: {test-class}::{test-method}
    Analysis: Test file was modified by this pipeline. Failure is in new code.
    Not a flaky test. Not a cross-ticket dependency.
    -> retry   = Re-run this ticket's pipeline
    -> context = Provide additional context for Cyrus
    -> skip    = Skip this ticket
    -> abort   = Cancel this ticket

• Hold downstream waves that depend on this ticket
• Independent waves may proceed

Recovery logging

All smart recovery actions are included in the cluster report and the swarm run log for post-mortem analysis by swarm-retro:

Smart Recovery Actions:
  PROJ-1003: [auto-retry: suspected flaky test — MC_CampaignTest::testTimeout] (succeeded)
  PROJ-1009: [auto-resequence: dependency on PROJ-1001 — MC_Billing::processRefund] (moved to Wave 3)

Step 4: Report cluster completion

When all waves complete (or all remaining tickets are blocked/aborted), report the cluster summary to ticket-swarm:

[Backend Lead] Cluster complete: 4/4 tickets processed

  Succeeded: 2 (PROJ-1003, PROJ-1007)
  Advisory:  1 (PROJ-1001 — analysis says this is a config change on the vendor side, not code)
  Blocked:   1 (PROJ-1002 — test failure in integration step)

  Waves executed: 3
  Agents spawned: 4
  Total files changed: 8
  Total tests written: 18

ticket-swarm aggregates reports from all team leads into the swarm progress dashboard.

Dependency edge cases

• Circular dependencies: If ticket A depends on B and B depends on A (from Jira Blocks links), flag this to ticket-swarm as unresolvable. Suggest the user merge the tickets or clarify the dependency direction.
• Single-ticket clusters: If the domain has only one ticket, skip dependency analysis and wave scheduling. Launch the pipeline directly.
• All-independent clusters: If no dependencies are detected, launch all tickets in a single wave (maximum parallelism).
• Branch chaining for sequential tickets: When ticket B depends on ticket A, B's branch should be created from A's completed branch (not from the default branch). This ensures B sees A's changes. The team lead instructs ticket-pickup to use the appropriate base branch.
• Pre-existing branches: Before creating any branch, check if one matching the ticket key already exists (git branch --list "*{key}*"). If found, use it — the user may have pre-created the branch manually. For chained tickets, verify the pre-existing branch is based on the correct parent (rebase onto A's branch if needed).

Truncation handling — sentinel scoping

The <<task-complete>> sentinel requirement is scoped by who owns the stage:

• Workflow-owned stages are exempt. When Step 3's team-lead-waves workflow path succeeds, each pipeline stage runs as agent() with the TICKET_RESULT schema — a schema-validated return is the completion signal, and a dead or truncated agent surfaces as null (attributed to its ticket and reported in blocked). Do not look for the sentinel there; its absence means nothing.
• Prose-orchestrated calls still require it. Every Agent tool call this skill makes directly — the LEGACY FALLBACK wave execution, Step 3.5 retries and re-runs, and any other direct pipeline invocation — must be verified to contain the <<task-complete>> sentinel before its output is consumed. See ~/.claude/_shared/agent-turn-cap-warning.md for the detection rule and the swarm-mode response (record, mark the ticket blocked with reason agent_truncated, move to the next ticket). Still emit the agent_truncated metric for these calls — see ~/.claude/skills/metrics-emit/SKILL.md → agent_truncated.

Maintenance

If you discover something during this task that would improve this skill, propose the change and ask me to confirm before saving it.