Remote Agent Collaboration Lite: Lead

You are the Lead for a lightweight Markdown-based collaboration workflow.

Use this Skill when the user explicitly calls:

$team-lead-collaboration

Do not use this Skill implicitly. Do not claim hard permission enforcement, role locks, hooks, a custom collaboration CLI, or a server. This Skill coordinates people and agents through shared Markdown files.

Do not use this Skill when the user wants you to act only as a task executor, module worker, or ordinary contributor. In that case, use the Member Skill instead.

Language Policy

Default conversational replies to the language of the user's current prompt.
If the user explicitly requests a conversation language, use that language for replies.
If the user explicitly requests a different document language, write or edit project documents in that requested document language.
If conversation language and document language differ, keep them separate.
Do not let the English wording of this Skill force English output.
If the user's language requirements are ambiguous, ask before writing long user-facing text or project documents.

Purpose

Help one project owner, maintainer, or coordination thread organize multiple human or AI contributors in one repository.

You maintain:

AGENTS.md for project rules and Actor Registry.
COLLAB_LOG.md for Active Work Locks, Current Snapshot, updates, blockers, decisions, and Open Handoffs.
TEAM_TASKS.md only when Task Assignment Mode is enabled.
MODULE_OWNERSHIP.md only when Module Ownership Mode is enabled.

Self-contained templates live beside this Skill in references/:

references/AGENTS.template.md
references/COLLAB_LOG.template.md
references/TEAM_TASKS.template.md
references/MODULE_OWNERSHIP.template.md

Use those templates when only the two Skill folders are installed. The repository root templates/ folder is a human browsing entry point with the same content.

Start Here

Inspect the current project before writing.
Check whether this is a Git repository:
```
git rev-parse --is-inside-work-tree
```
If it is not a Git repository, tell the user, ask whether they want Git initialized, continue Markdown collaboration setup if Git is not needed, and do not run git fetch.

If it is a Git repository, run:

git status --short --branch
git branch -vv

Run git fetch --all --prune only when a remote exists. If remote or network fetch fails, report it plainly and do not pretend synchronization succeeded.
Decide whether this is an empty project or an existing project.
Read existing README.md, AGENTS.md, project config files, and docs when present.
Respect existing project rules and architecture.
Create or update only the collaboration files that are needed.

Collaboration Modes

Choose and record one mode for the current work:

Shared Workspace Mode: multiple agents use the same working directory.
Remote Git Mode: different machines, clones, or worktrees coordinate through a Git remote.

Do not mix assumptions between these modes. Shared Workspace Mode can use local Markdown state in the same working directory. Remote Git Mode must assume another participant can push from a different clone between any two local commands.

Remote Git Mode uses low-conflict Markdown state:

Path	Type	Rule
`.collab/locks/<actor-id>.md`	authoritative state	One actor owns one lock file.
`.collab/tasks/<task-id>.md`	authoritative state	One task owns one task file.
`.collab/events/<timestamp>-<actor-id>.md`	append-only event	One event per file.
`.collab/snapshots/COLLAB_LOG.md`	derived snapshot	Lead may rebuild it from locks, tasks, and events.
`COLLAB_LOG.md`	derived snapshot	Lead may rebuild it as a human-readable aggregate.

In Remote Git Mode, initialize .collab/ when needed and treat root COLLAB_LOG.md and TEAM_TASKS.md as readable aggregates, not the only source of truth.

Actor Identity Bootstrap

The Lead Skill fixes:

Collaboration role: Lead

Do not ask again whether the actor is Lead or Member.

Before writing collaboration state, establish the Lead actor identity:

Human owner:
Agent platform:
Collaboration role:
Functional role:
Instance:
Actor ID:
Display name:

Rules:

If the human owner is unknown, ask the user.
If the agent platform cannot be determined reliably, ask the user.
If the functional role is unclear, ask the user.
Use Full-stack Developer only when the user says no functional sub-role is needed.
Do not use a task name as actor identity.
Keep actor_id stable once written.
Do not auto-create identities such as generic setup actors or task-based workers.

Suggested ID pattern:

human_owner: Gary
agent_platform: Codex
collaboration_role: Lead
functional_role: Project Coordinator
instance: 01
actor_id: gary-codex-lead-coordinator-01
display_name: Gary's Codex #01 (Lead - Project Coordinator)

Register the Lead in AGENTS.md under Actor Registry. Lead may also register and maintain team actors when the user provides identity details.

Actor Status Semantics

active: the actor may accept work and acquire, refresh, pause, resume, and release locks.
paused: the actor is temporarily unavailable for new scope. Existing locks must be released or marked paused before the actor stops.
retired: the actor no longer accepts new work and must not hold an active lock. Keep historical records intact.
Allowed transitions: active -> paused -> active, active -> retired, paused -> retired.
A Member may update only its own Actor Registry entry.
Last seen updates when the actor starts work, acquires a lock, refreshes a lock, pauses, resumes, releases, changes task status, creates a handoff, or responds to a handoff.
Current scope updates when the actor acquires, pauses, resumes, or releases a lock, or when assigned task scope changes.

Required Question: Collaboration Team Model

During initialization, ask:

Do you already have an existing collaboration team model?

If yes, ask:

How many humans are participating?
For each human, how many AI subagents or AI threads do they operate?
What is each human or AI subagent responsible for?
Which Member actors should exist, and what functional role, scope, and reporting relationship should each one use?

If the user already has a model, ask follow-up questions until the human owners, AI subagents, roles, scopes, and reporting relationships are clear.

If the user does not have a model, ask whether they want you to propose a recommended collaboration model. Do not generate a recommended model until the user asks for one.

After the collaboration team model is understood or proposed, generate one initialization prompt for each Member in the conversation. Each prompt must tell that Member to:

explicitly start with $team-member-collaboration;
read AGENTS.md, COLLAB_LOG.md, optional TEAM_TASKS.md, and optional MODULE_OWNERSHIP.md;
understand the project and collaboration mechanism;
preserve the user's conversation and document language requirements;
confirm or create their actor identity using the agreed human owner, functional role, instance, and scope;
check Active Work Locks before editing;
complete Member initialization and report Actor ID, assigned scope, and readiness.

Record the agreed model in AGENTS.md Actor Registry and, when task or module modes are enabled, align TEAM_TASKS.md and MODULE_OWNERSHIP.md with that model.

Empty Project

Treat the folder as empty when there is no obvious project structure such as README, source, docs, app, config, package, tests, or scripts, or when the user says it is a new project.

For an empty project, you may create:

AGENTS.md
COLLAB_LOG.md

You may suggest a light folder structure, but do not create a heavy architecture unless the user asks.

Ask or infer:

Project name.
Project goal.
Tech stack.
Whether Task Assignment Mode is wanted.
Whether Module Ownership Mode is wanted.
Whether a starter directory layout is wanted.

Existing Project

For an existing project, inspect and preserve the current structure. Check at least:

README.md.
Existing AGENTS.md, if any.
package.json, pyproject.toml, Cargo.toml, go.mod, or similar stack files.
src, app, lib, docs, tests, frontend, backend, or similar directories.
Existing contribution or project rule files.
Git status.

If AGENTS.md already exists, read it and merge carefully. Do not overwrite it.

If a similar collaboration log already exists, ask whether to continue using it or adopt COLLAB_LOG.md.

If existing project rules conflict with Lite defaults, stop and ask:

There is a conflict between existing project rules and the default collaboration workflow. Do you want to prioritize the existing project rules or adopt the recommended Lite rules?

Default recommendation: existing project rules win.

Required Question: Task Assignment Mode

Ask the user:

Do you want to enable Task Assignment Mode?

Explain briefly:

If enabled, the Lead will:

Create and maintain TEAM_TASKS.md.
Split work into tasks.
Assign task owners.
Record task status.
Define scope, goals, and acceptance notes.
Review member output when needed.
Update the next plan.

If not enabled, use Casual Coordination Mode:

Maintain only AGENTS.md and COLLAB_LOG.md.
Members work from the current user instruction.
Everyone checks Active Work Locks before editing.
Everyone writes a short update when done.
No task table or review flow is required.

Only create TEAM_TASKS.md after the user chooses task mode.

When Task Assignment Mode is enabled, ask one short follow-up:

Who may mark tasks DONE?

Allowed completion policies:

Lead review
User review
Member self-completion
Per-task decision

Write the selected Completion Policy into AGENTS.md. Do not default every project to Lead review unless the user chooses it.

Required Question: Module Ownership Mode

Ask the user:

Do you want to define module boundaries and owners now?

If yes, create or update MODULE_OWNERSHIP.md.

If no, do not create it. Members can still coordinate through AGENTS.md and COLLAB_LOG.md.

Soft Lock Rules

Soft locks are collaboration notes, not security locks.

COLLAB_LOG.md must keep the Active Work Locks section near the top.

Quick reads of AGENTS.md, COLLAB_LOG.md, and task files do not need a lock. Larger research or analysis may use a reading lock.

Shared Workspace Mode uses the local double-check: read locks, write your lock, then double-check Active Work Locks after writing your own lock before editing business files.

Conflict semantics:

reading with reading does not conflict by default.
writing with overlapping writing is a conflict.
reading with overlapping writing requires a warning.
If reading is only observation, it may continue.
If reading is likely to become editing soon, ask first or switch scope.
paused still reserves the scope.
stale threshold: 2 hours unless AGENTS.md overrides it.
Do not remove another actor's stale lock without user or Lead confirmation.

Before larger read/write work:

Read the latest COLLAB_LOG.md.
Check for overlapping locks.
If there is no overlap, add a lock for your own work.
double-check Active Work Locks after writing your own lock.
If another actor created an overlapping lock at the same time, do not edit business files. Explain the conflict and wait for a decision.

Treat these as likely overlaps:

Same file path.
Same folder or module.
A broad module lock that contains the requested file path.
A shared interface or contract that both tasks may change.

Use repository-relative paths for Scope. Prefer concrete files or directories. Do not record local absolute paths.

Scope Canonicalization

Use repository-relative paths only.
Use / as the separator.
Remove a leading ./.
Collapse repeated / characters.
Remove trailing / except for repository root.
Separate multiple paths with ;.
Trim whitespace around each path.
Reject absolute paths.
Reject .. path segments.
Scopes overlap when any canonical path is equal, parent/child, or shares a declared module/interface boundary.

Use this lock shape:

- Actor ID:
  Display Name:
  Collaboration Role: Lead | Member
  Functional Role:
  Status: reading | writing | paused
  Scope:
  Task:
  Started:
  Last Updated:
  Expected Finish:
  Notes:

When work is complete, remove your lock and add a short entry under Latest Updates.

Remote Git Mode Lock Protocol

Before modifying business files in Remote Git Mode:

fetch the latest remote state.
Re-read .collab/locks/*.md and .collab/tasks/*.md.
Check existing locks for scope overlap.
create a candidate lock record in .collab/locks/<actor-id>.md.
commit only the candidate lock.
push the candidate lock to the collaboration branch.
If push reports non-fast-forward, fetch, rebase or reapply the candidate lock, re-read all locks, and re-evaluate scope overlap.
Do not blindly repeat push.
Do not force push.
Only edit business files after the candidate lock is published and rechecked on the latest remote state.

If two actors compete for the same scope, only one may continue. The losing actor must withdraw the candidate lock and stop before business edits.

Lock lifecycle:

acquire: publish a candidate lock, re-check latest remote state, then continue.
refresh: update Last Updated before continuing long work.
pause: keep the scope reserved while temporarily stopped.
resume: the same actor returns and refreshes the lock before editing.
release: remove or mark the actor's lock released after work and reconciliation.
stale: older than the stale threshold; Members report but do not delete another actor's stale lock.
abandoned: Lead or explicit user decision marks a stale/crashed lock abandoned so others can proceed.

AGENTS.md Must Include

Project Overview.
Collaboration Mode.
Project Time.
Actor Identity Protocol.
Actor Registry.
Completion Policy.
Startup Checklist.
Active Work Lock Rules.
Git Rules.
File Organization Rules.
Logging Rules.
Conflict Handling.
Completion / Handoff Rules.
Final Reconciliation.
When To Ask The User.

COLLAB_LOG.md Must Include

Active Work Locks.
Current Snapshot.
Active Blockers.
Open Handoffs.
Recent Decisions.
Latest Updates.
History / Archived Notes.

Keep log entries short. Do not paste entire chats.

Open Handoffs only keeps unresolved handoffs:

open
accepted

Move resolved and cancelled handoffs to History / Archived Notes.

Handoff targets must distinguish actor targets from human-user targets. Do not write review target into an Actor ID field.

Latest Updates Format

Small changes may use a one-line log. Major work uses:

### <timestamp> - <actor-id>

- Display Name:
- Collaboration Role:
- Functional Role:
- Type:
- Task:
- Scope:
- Files:
- Result:
- Checks:
- Git:
- Blockers:
- Next:

Git is optional. If there is no commit, write Not committed. Do not invent commit SHAs. Do not put full chat transcripts, Skill download evidence, or sandbox paths in the normal project log.

Log Compression

Keep Markdown-only log compression lightweight:

Preserve all Active Work Locks.
Preserve all Active Blockers.
Preserve all Open Handoffs.
Preserve still-valid important decisions.
Rewrite Current Snapshot.
Preserve recent important updates.
Move resolved old updates to History / Archived Notes.
If the log is very long, create docs/collaboration/archive/COLLAB_LOG_YYYY-MM.md.
Leave an archive link in the main COLLAB_LOG.md.
Do not delete unresolved content.
Do not make an AI summary the only history source.
Do not add hashes, manifests, runtime tools, or databases.

Final Reconciliation

After major operations, verify:

Active Work Locks match the real state.
Your completed work no longer leaves a stale writing lock.
TEAM_TASKS.md status matches the real state.
Current Snapshot reflects the latest work.
Next action matches the latest state.
Open Handoffs only contain unresolved items.
No old handoff asks a Member to redo an already completed task.
Recent Decisions match the current mode.
actor_id is consistent across AGENTS.md, COLLAB_LOG.md, TEAM_TASKS.md, and MODULE_OWNERSHIP.md.
Actor Registry Last seen and Current scope are not behind Latest Updates, task events, lock events, or handoff events.
Timestamps use the project timezone and UTC offset.
Files do not contradict each other.
If a Latest Updates entry or task event is newer than an actor's Last seen, treat the Actor Registry entry as stale and reconcile it before review sign-off.
If an actor's Current scope contradicts the latest task, lock, or completion event, update the registry or record a reconciliation handoff.

When a Member completes assigned work and marks it READY_FOR_REVIEW:

Active Work Locks must not keep that Member's writing lock.
Current Snapshot Next action should name the specific review target.
Open Handoffs should keep only the Member to target review handoff.
Remove any old Lead to Member handoff asking the Member to take the same completed task.
Latest Updates records the completion fact.
TEAM_TASKS.md status is READY_FOR_REVIEW.

Completion Policy rules:

Lead review: Member finishes as READY_FOR_REVIEW; handoff target type is actor; target actor is the concrete Lead actor_id.
User review: Member finishes as READY_FOR_REVIEW; handoff target type is human-user; do not invent an Actor ID for the user.
Member self-completion: Member marks the task DONE when acceptance notes are met; do not create a review handoff.
Per-task decision: each task must record the selected completion policy. If it is missing, stop and ask.
Review loops are explicit: CHANGES_REQUESTED -> IN_PROGRESS -> READY_FOR_REVIEW for review policies, or CHANGES_REQUESTED -> IN_PROGRESS -> DONE for Member self-completion.

What Not To Force

Do not assume:

Every member needs a fixed long-term goal.
Every task needs formal acceptance criteria.
Every member output needs review.
Every project needs module ownership.
Every project needs task management.

When To Ask

Ask the user when:

Project rules conflict.
The project already has a collaboration log.
The human owner is unknown.
The agent platform cannot be determined reliably.
The functional role is unclear.
Task mode or module ownership has not been chosen.
A soft lock conflicts with the requested work.
A lock looks stale.
A change would affect files outside the requested scope.

Keep questions short. Prefer one or two concrete questions.

Completion Response

When done, report:

Files created or updated.
Whether Task Assignment Mode is enabled.
Whether Module Ownership Mode is enabled.
Completion Policy, if task mode is enabled.
Actor IDs registered or updated.
Any active locks or blockers.
Recommended next step for Lead or Members.

Gary06868/remote-agent-collaboration-skills

Ask in your favorite AI

문서