AgentSkillsCN

agent-team-protocol

通过文件所有权、TDD 工作流、Git 协调以及团队生命周期管理，统筹并行代码执行团队。定义孵化模板、超时策略与关停流程。

SKILL.md
--- frontmatter
name: agent-team-protocol
description: >
  Governs parallel code execution teams with file ownership, TDD workflow,
  git coordination, and team lifecycle management. Defines spawn templates,
  timeout policies, and shutdown procedures.
triggers:
  - /coding-workflows:execute-issue
domains: [execution, agent-teams]
user-invocable: false
disable-model-invocation: true

Agent Team Protocol

This protocol governs parallel code execution teams (file ownership, TDD, git). For multi-round specialist deliberation, see the coding-workflows:deliberation-protocol skill.

Reference protocol for execute-issue when using parallel agent teams. Invoked when Execution Topology guard clause routes here.

Phase 0: Contract-First Handoff (~5 min)

Lead defines interface contracts on the feature branch:

  1. •Write model/type shells -- field names and types only, no validators or logic
  2. •Write interface/protocol method signatures -- return types, no logic
  3. •Add module exports for new modules
  4. •Commit to feature branch

Guidance: Write interface contracts in the project's type system. Examples:

  • •Python: Pydantic models, Protocol/ABC classes
  • •TypeScript: interfaces and type definitions
  • •Rust: trait definitions and struct shells
  • •Go: interface definitions
  • •Ruby: method signatures with YARD docs

Phase 0 should produce <20 lines per model. If writing more, you are over-specifying.

Optionally write integration test skeletons marked as skipped (e.g., pytest.mark.skip, it.skip, #[ignore]).

Phase 1: Team Setup

  1. •TeamCreate with descriptive name (e.g., "issue-42-feature-name")
  2. •TaskCreate per independent layer. One task per layer (not per TDD step). Description includes:
    • •Plan excerpt for this layer
    • •Exact files the agent owns
    • •Test command (from resolved config)
    • •"Follow TDD-First Completion Loop independently"
  3. •TaskUpdate with addBlockedBy for layer dependencies:
    • •Models/types layer: no dependencies
    • •Service/logic layer: blockedBy models if it imports model types
    • •API/route layer: blockedBy models
    • •Integration: blockedBy all layers (lead handles)
  4. •Spawn one general-purpose agent per task via Task with team_name and name
  5. •TaskUpdate to assign owner per agent

Phase 2: Parallel Execution

Agents work independently:

  • •Run TDD-First Completion Loop on assigned layer
  • •Commit ONLY owned files (git add by specific filename, NEVER git add .)
  • •git pull --rebase before each commit
  • •If push fails: run git pull --rebase and retry up to 3 times
  • •NEVER modify root-level test config or shared module exports -- create layer-specific test fixtures in your test subdirectory
  • •Mark task completed via TaskUpdate when all layer tests pass
  • •If cannot resolve after 3 attempts: SendMessage to lead, do NOT mark completed

Phase 3: Convergence Check

Wait for idle notifications (automatic, do NOT poll in tight loop). Check TaskList to confirm all tasks completed.

  1. •git pull --rebase
  2. •Run the full test suite from resolved config
  3. •Run the typecheck command from resolved config (if configured) with cross-boundary checking
  4. •If failures: lead fixes interface mismatches directly

Partial failure recovery:

  • •If team times out (15-minute cap): run git log and the test suite to assess state
  • •If tests fail due to missing layers: identify which layers are incomplete
  • •Complete incomplete layers sequentially (lead implements)
  • •Do NOT discard completed agents' work -- it is already committed

Phase 4: Integration

  1. •Fill in test skeletons with real assertions
  2. •Register routes/handlers in shared files (lead only)
  3. •Run integration tests from resolved config
  4. •Cross-layer refactoring happens here, not during Phase 2

Lead role clarity:

  • •Lead WRITES: contract shells (Phase 0), shared file modifications (Phase 4), integration tests (Phase 4), interface mismatch fixes (Phase 3)
  • •Lead does NOT WRITE: layer-specific implementation code or unit tests -- those belong to agents

Phase 5: Shutdown

  1. •SendMessage(type: shutdown_request) to each agent, sequentially (not broadcast)
  2. •Wait 60 seconds for shutdown_response per agent
    • •Approved: proceed to next
    • •Rejected: address agent's concern first
    • •No response: proceed (agent will timeout)
  3. •TeamDelete (retry up to 2x)
  4. •Final cleanup: If TeamDelete fails after 2 retries, remove team directories:
    bash
    [ -n "$TEAM_NAME" ] && rm -rf ~/.claude/teams/$TEAM_NAME ~/.claude/tasks/$TEAM_NAME
  5. •Orphan check at startup: Before creating a new team, check ls ~/.claude/teams/ for orphans from previous sessions

Spawn Prompt Template

Each agent receives (mandatory sections):

code
## Your Assignment
[Task subject]

## Plan Excerpt
[Layer-specific section from plan]

## File Ownership (CRITICAL)
You own ONLY these files:
- [file list]
Do NOT edit files outside this list.
NEVER modify root-level test config -- create your own in your test subdirectory.
If you need a file you don't own changed, message the lead.

## Git Workflow
Branch: {branch from resolved config branch_pattern}
Before every commit:
1. git pull --rebase
2. git add [your files by name -- NEVER git add .]
3. git commit
4. git push (if push fails, pull --rebase and retry up to 3x)

## TDD Workflow
1. RED: Write test, confirm fails for right reason
2. GREEN: Minimum implementation to pass
3. REFACTOR: lint + typecheck, confirm still passing
Test command: {commands.test.focused from resolved config}

## Completion
All tests passing -> TaskUpdate(completed)
3 failed attempts on same error -> SendMessage to lead, do NOT mark completed

Team Timeout

Maximum team duration: 15 minutes from TeamCreate. If not all tasks complete:

  1. •Send shutdown_request to all agents
  2. •Wait 30 seconds
  3. •TeamDelete (force cleanup if needed)
  4. •Complete remaining work sequentially
  5. •Note timeout in Session Checkpoint