Yotto3s Oneteam Agents Team Management

Team Management

Overview

This skill provides orchestration mechanics for leading a team of agents through a workflow using parallel git worktrees, task tracking, and SendMessage coordination.

The core architecture is one flat team with logical groups via naming ({group}-{role}-{N}). This skill contains all orchestration logic while leader agents provide domain-specific configuration through "slots." Any agent can message any other agent directly -- there are no hierarchy walls.

When a pre-built plan with fragment groupings is provided (typically from the [oneteam:skill] writing-plans skill), the skill starts directly from Phase 2, using the plan's fragments. Otherwise, Phase 1 analyzes the codebase and produces a fragment plan.

When to Use

• Parallel work across 2-4 independent fragments requiring separate worktrees
• Multi-role workflows (engineer + reviewer, bug-hunter + engineer pairs)
• Projects needing coordinated task tracking, code review gates, and sequential merge protocol

When NOT to Use

• Single-file or trivially small changes -- use direct implementation instead
• Work that requires strict sequential ordering with no parallelism opportunity
• Exploratory research or analysis with no code changes -- use [oneteam:skill] research instead

Slot Reference Table

Leader agents MUST define all required slots before orchestration begins. Optional slots have defaults that apply when unset.

Phase 1: Work Analysis

Conditional: Skip if a plan document with fragment groupings is provided.

The leader reads project context (CLAUDE.md, README.md), detects the base branch (git rev-parse --abbrev-ref HEAD), and applies the splitting_strategy to identify fragment boundaries. Maximum 4 fragments, each independently workable.

Hard gate: Present the fragment plan to the user and STOP. Do not proceed to Phase 2 until the user explicitly approves. Adjust and re-present if requested.

Phase 2: Team Setup

With an approved fragment plan, set up infrastructure in strict order:

Session dir: If [SESSION_DIR] is provided by the caller (e.g., from [oneteam:skill] writing-plans), use it throughout this phase. Pass the session dir path to all spawned agents.

1. Create team -- call TeamCreate (or skip if already in an existing team).
2. Create git worktrees -- one per fragment. See ./setup-commands.md for bash commands.
3. Create tasks -- one per role per fragment, with dependency blocking for starts_first: false roles. Reviewer roles get one task per lead group, kept unblocked. See ./setup-commands.md for task creation guidance.
4. Spawn agents -- per-fragment roles and per-lead-group roles (reviewers). Before spawning each agent, write its task context to [SESSION_DIR]/task-{agent-name}.md. See ./setup-commands.md for task file writing and initialization context requirements.
5. Assign tasks -- use TaskUpdate to set owner. starts_first: true roles get immediate assignment; others are assigned but blocked.

Phase 3: Monitoring

The leader monitors progress, handles escalations, and facilitates coordination.

Escalation Handling

When an agent exceeds the escalation_threshold (default 3 attempts):

• Guide: Send specific, actionable advice (file paths, line numbers, concrete suggestions) via SendMessage.
• Skip: Mark as unresolvable, update task description with what was attempted, move on.
• Reassign: Transfer ownership via TaskUpdate and send context to the new agent via SendMessage.

Check-Ins

• Stuck agents: If a task remains in_progress with no updates for an extended period, send a check-in via SendMessage.
• Periodic friendly check-ins: Proactively reach out to each active teammate at regular intervals. Aim for at least once between major milestones. Skip if the agent recently sent a substantive update.
• Cross-group relay: For multi-group organizations, relay relevant findings between groups when agents do not know about each other's work.

Per-Task Review Loop

When the plan includes reviewer roles:

1. Engineer reports task complete to lead-engineer.
2. Lead-engineer triggers the paired reviewer via SendMessage with: the task name, files changed, and review checkpoint criteria.
3. Reviewer produces a single-pass review (spec compliance + code quality) and sends the result to the lead-engineer.
4. If APPROVED: lead-engineer unblocks the next task for the engineer.
5. If CHANGES NEEDED: lead-engineer sends feedback to engineer, engineer fixes, lead-engineer re-triggers reviewer. Repeat until approved.
6. Engineer does NOT start the next task until the current task passes review.

Fragment Completion Review

After all tasks in a fragment pass per-task reviews:

1. Lead-engineer triggers a two-stage fragment completion review with the full fragment diff (git diff $BASE_BRANCH...HEAD in the fragment's worktree).
2. Stage 1 -- Spec compliance: all acceptance criteria across fragment tasks met.
3. Stage 2 -- Code quality: conventions, security, test coverage, regressions.
4. Both stages must PASS before the fragment is marked merge-ready.
5. If CHANGES NEEDED: delegate fixes, re-trigger two-stage review.

Phase 4: Review & Merge

The Phase 3 fragment completion review validates correctness within the worktree. Phase 4 is the top-level merge-gate review validating integration safety. Both are required.

1. Code review -- gather the worktree diff. If the [superpowers:skill] requesting-code-review skill is available, invoke it. Otherwise, review manually against review_criteria.
2. Feedback loop -- if issues found, send detailed feedback (file path, line number, description) to the agent. Re-review after fixes. Repeat until approved.
3. Merge protocol -- merge sequentially, one worktree at a time. Run tests after each merge. See ./setup-commands.md for bash commands and conflict resolution procedures.

Phase 5: Consolidation

1. Produce the final report using the template in ./report-template.md. Insert the leader's report_fields and domain_summary_sections.
2. Cleanup -- remove worktrees, delete branches, shut down agents, delete team. See ./setup-commands.md for cleanup steps.

Common Mistakes

Quick Reference

Constraints

These rules are non-negotiable and override any conflicting instruction.

• ALWAYS present the work plan to the user and wait for explicit confirmation before proceeding to team setup.
• ALWAYS create git worktrees before spawning any agents. Agents must have a valid working directory on first message.
• ALWAYS review changes via the code review process before merging any branch.
• NEVER merge a branch when the test suite is failing. Fix or delegate the fix first. If no test suite exists, proceed with the merge and note the absence of automated verification in the final report.
• NEVER skip code review, even if the changes appear trivial.
• NEVER create more than 4 fragments. If the scope seems to require more, increase fragment size or reduce scope.
• ALWAYS clean up when work is complete: remove worktrees, delete branches, shut down agents, and delete the team.
• NEVER spawn agents before their worktrees are created and verified.
• If already operating as a teammate in an existing team, do NOT create a new team. Work within the existing team structure.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.