---
description: Collaborate with another agent via a shared markdown file
argument-hint: [initial task description]
---

# Collaboration Session

You are collaborating with another agent (which may be a different AI, or a human driving one) via a shared markdown file. Coordinate entirely through that file.

## Preconditions

This is for LOCAL use only. Both agents run on the same machine and share the same local filesystem, and both are local coding agents that can read and write local files. There is no network transport: the shared file is reached by its local path, and change detection relies on both sides editing that one file in place. Do not use this to coordinate across machines.

## Task

$ARGUMENTS

## Roles

You are **Agent A** (the agent running this command). The collaborator is **Agent B**. These labels are fixed for the whole session regardless of who writes next, so "who is who" never depends on point of view.

## Setup

1. Create a shared collaboration file named `collab-<unix-timestamp>.md` in the operating system's temporary directory. Resolve that directory the way the current platform does rather than hardcoding a path: `$TMPDIR` or `/tmp` on Linux and macOS, `%TEMP%` on Windows, or your runtime's standard temp-directory lookup if you are unsure. Use the OS-native absolute path and path separators, and report the full absolute path to the user. Give the file this structure:

   ```markdown
   # Collaboration: <short task title>

   **Started:** <ISO 8601 UTC timestamp>
   **Agent A:** <your role, e.g. "Code/analysis agent">
   **Agent B:** <unknown until first reply; fill in once known>
   **Status:** in progress

   ## Task

   <restate the task from $ARGUMENTS>

   ## Context

   <any relevant context, file paths, constraints>

   ## Log

   <!-- Both agents append entries below, in order, at the very end of the file.
        Never edit anything above this comment. Never delete a prior entry.
        Each entry uses this exact format (choose N as the largest entry number
        already present, plus one):

   ### Entry N -- <author: Agent A or Agent B> (ISO 8601 UTC timestamp) [question|answer|note]

   <your text>

   -->
   ```

2. Report the exact file path to the user and give them this message to relay to Agent B:

   > You are collaborating with another agent (Agent A) via a shared markdown file at `<path>` on this machine. You are Agent B.
   > - Read the whole file: the task, the context, and every entry under `## Log`.
   > - To reply, APPEND a new entry to the very END of the file. Never insert above existing entries, and never edit or delete them. Use this exact format, choosing N as the largest entry number already present plus one:
   >   `### Entry N -- Agent B (ISO 8601 UTC timestamp) [question|answer|note]`
   >   followed by a blank line and your text.
   > - Tag the entry `[question]` when you need a reply, `[answer]` when responding, `[note]` otherwise.
   > - Write only when it is your turn: in response to a new entry from Agent A, or to ask an opening question. Do not write two entries in a row without a reply in between.
   > - When you consider the collaboration finished, set the `**Status:**` line to `complete` and append a final `[note]` saying you are done.
   > - If anything is ambiguous, ask the user driving you before writing.

## Watch loop

Coordination is turn-based. Do NOT attempt an endless in-turn loop that never returns to the user. Each time you check:

- Re-read the whole file and compare it against the last version you saw. A content diff is the reliable signal; a changed modification time is only a cheap hint that a re-read is worth doing.
- If there are new entries from Agent B, surface their full new content to the user (never summarize silently), then respond by appending your own `### Entry N -- Agent A ...` entry.
- If you can wait efficiently, block for a single bounded interval until the file changes or a timeout elapses, then report. Use whatever the current OS offers for this (for example a file-watch or a `stat` check on Linux and macOS, `Get-Item` in Windows PowerShell), and never a command that exists on only one OS. Otherwise, tell the user you are waiting and let them prompt you to check again.
- Stop when the file's `**Status:**` is `complete`, or when either party posts a final done entry, or when the user says the collaboration is complete.

## Rules

- Append only, at the end of the file, under `## Log`. Never edit or delete an existing entry, and never touch anything above `## Log` -- the file is the audit log of the collaboration.
- Every entry carries its author (Agent A or Agent B), a sequential N (largest present plus one), and an ISO 8601 UTC timestamp. If you ever find two entries sharing a number, leave both and order them by timestamp.
- Take turns: write in response to the other side, not repeatedly on your own.
- If the task, a response, or a request is ambiguous, stop and ask the user directly before writing to the file or continuing to watch. Do not guess on behalf of either agent.