Agent Handoff

## Agent Handoff (always active)
<!-- agent-handoff:v3 -->

You are part of a multi-agent workflow. Multiple AI agents work on this project
at different times. Each agent has isolated conversation history. A shared `.ai/`
directory bridges that gap.

**ON EVERY CONVERSATION START — before doing any work**, read these files:

1. `.ai/PROJECT.md` — Tech stack, architecture, conventions
2. `.ai/PATHS.md` — Key files and reference document index
3. `.ai/PLAN.md` — Current plan and task status
4. `.ai/conversations/HANDOFF.md` — What other agents did, what's active, blockers

If any file is missing, empty, or still contains installer placeholders, repair the
handoff system before continuing: create the `.ai/` directory structure, scan the
project, and populate the context files. See the templates in the agent-handoff
skill reference files for exact formats.

Before writing timestamps or session filenames, get the real local time from the
environment (`date '+%Y-%m-%d %H:%M %Z'` and `date '+%Y-%m-%d/%H%M%S'` on Unix-like
systems). Do not infer the date from model memory, old docs, or previous handoff
entries.

**BEFORE YOU FINISH EVERY RESPONSE**, complete the handoff write-back. Do not stop
after only reading handoff context.

- **Always:** Append to `.ai/conversations/LOG.md`.
- **Always for file changes, tests, investigations, plans, or decisions:** update
  `.ai/conversations/HANDOFF.md` and create a session file in
  `.ai/conversations/sessions/YYYY-MM-DD/`.
- **If architecture/design decision:** Write to `.ai/conversations/decisions/`.
- **If project structure changed:** Update `.ai/PATHS.md`.
- **If plan status changed:** Update `.ai/PLAN.md`.
- **In your final response:** mention that handoff was updated, or explain why no
  handoff write was needed.

Session filenames must be unique and sortable:
`.ai/conversations/sessions/YYYY-MM-DD/HHMMSS-agent-task-slug.md`.

Identify yourself by agent name in all writes. For simple Q&A with no file changes,
a one-liner in LOG.md is sufficient.


#!/usr/bin/env bash
set -euo pipefail

# Agent Handoff — Universal Installer
# Installs the agent-handoff skill for ALL detected agents in a project.
#
# Usage:
#   curl -fsSL https://raw.githubusercontent.com/wecansync/agent-skills/main/skills/agent-handoff/install.sh | bash
#   # or
#   bash install.sh [--project-dir /path/to/project]

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_DIR=""
INJECT_MARKER="## Agent Handoff (always active)"
INJECT_VERSION_MARKER="<!-- agent-handoff:v3 -->"

# Parse flags
while [[ $# -gt 0 ]]; do
  case $1 in
    --project-dir) PROJECT_DIR="$2"; shift 2 ;;
    --help|-h)
      echo "Agent Handoff — Universal Installer"
      echo ""
      echo "Usage:"
      echo "  bash install.sh                          # install in current directory"
      echo "  bash install.sh --project-dir /path/to   # install in specific project"
      echo ""
      echo "This script MUST be run from your project root (or use --project-dir)."
      echo "Do NOT install at user scope (~/.claude/skills/) — the .ai/ context"
      echo "files and agent config snippets must live inside the project."
      exit 0
      ;;
    *) shift ;;
  esac
done

# Resolve project directory
if [[ -z "$PROJECT_DIR" ]]; then
  PROJECT_DIR="$(pwd)"
fi
PROJECT_DIR="$(cd "$PROJECT_DIR" && pwd)"

# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'

info()    { echo -e "${BLUE}[info]${NC} $1"; }
success() { echo -e "${GREEN}[done]${NC} $1"; }
warn()    { echo -e "${YELLOW}[skip]${NC} $1"; }
err()     { echo -e "${RED}[error]${NC} $1"; }
step()    { echo -e "${GREEN}  +${NC} $1"; }

copy_if_different() {
  local source="$1"
  local target="$2"

  if [[ ! -f "$source" ]]; then
    return
  fi

  mkdir -p "$(dirname "$target")"

  if [[ -f "$target" ]] && [[ "$(cd "$(dirname "$source")" && pwd)/$(basename "$source")" == "$(cd "$(dirname "$target")" && pwd)/$(basename "$target")" ]]; then
    return
  fi