Skill: Handoff Coordination
Purpose
Ensure safe, explicit, and low-friction coordination between agents working on the same feature or overlapping areas of the codebase.
This skill governs runtime collaboration, not planning or workflow design.
It uses docs/team/HANDOFF.md as the single source of truth for:
- •active work
- •ownership
- •locks
- •blockers
- •next handoff
Trigger
Use this skill whenever ANY of the following occur:
- •more than one agent is working on the same feature
- •multiple agents may touch overlapping files, contracts, or schemas
- •ownership of work is changing between agents
- •work is blocked waiting on another agent
- •uncertainty exists about “who should act next”
Authoritative reference
This skill treats the following document as authoritative runtime state:
- •
docs/team/HANDOFF.md
If coordination information exists elsewhere, it MUST be reconciled into HANDOFF.
Inputs
- •
docs/team/HANDOFF.md - •current feature context
- •current editor or agent role
- •planned next action (if known)
Outputs
This skill MUST update docs/team/HANDOFF.md with one or more of the following:
- •active editor / agent
- •locked areas (files, domains, contracts)
- •explicit blockers
- •handoff notes
- •next expected agent or role
All updates must reflect current reality, not intent.
What this skill manages (and nothing more)
Active ownership
- •Who is currently working
- •On what feature
- •On which areas
Locks
- •What is temporarily exclusive
- •Why the lock exists
- •When it should be released
Blockers
- •What is preventing progress
- •Who owns the unblock
- •What is required to proceed
Handoffs
- •Clear transfer of responsibility
- •Context needed for the next agent
- •Explicit “ready for handoff” signals
Rules (strict)
- •There MUST be at most one active editor per locked area.
- •Locks MUST be explicit; implicit locks are not allowed.
- •Blockers MUST name an owner and a condition to clear.
- •Handoffs MUST include sufficient context for the next agent to proceed.
- •HANDOFF.md must reflect reality, not aspiration.
If these conditions are not met, work MUST stop.
Explicit non-responsibilities
This skill MUST NOT:
- •plan work or assign tasks
- •prioritize features
- •enforce workflow phases (use
workflow-enforcement) - •judge code quality or correctness
- •resolve product or scope questions
- •modify contracts directly
It only coordinates who is doing what, right now.
Interaction with other skills
This skill frequently interacts with:
- •
workflow-enforcement
→ to ensure coordination respects workflow gates - •
contract-handshake-and-freeze
→ to lock or unlock contracts during negotiation - •
integration-slice-orchestration
→ to sequence FE/BE work safely - •
bug-management
→ to log coordination failures that cause defects
This skill does not replace any of them.
Failure handling
If coordination cannot be resolved:
- •Record the conflict in
docs/team/HANDOFF.md - •Identify all involved agents or roles
- •State the blocking condition clearly
- •Escalate to the Lead for resolution
- •Stop further work until resolved
Working around coordination failures is prohibited.
Acceptance criteria
This skill is successful when:
- •parallel work does not conflict
- •ownership is always explicit
- •blocked work is visible and actionable
- •handoffs require minimal re-explanation
- •coordination failures are detected early
Design principle
This skill manages runtime state, not intent or design.
If this skill starts making decisions about what to build or how to build it, it is incorrectly scoped.