docs: add multi-agent memory best practices and scaffold script

scripts/scaffold-agent-memory.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Create a standard folder scaffold for one agent inside an existing memory git repository.
+# Usage:
+#   ./scripts/scaffold-agent-memory.sh --repo /path/to/memory-repo --agent agent-a
+
+REPO_ROOT=""
+AGENT_ID=""
+DEFAULT_BRANCH="main"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo)
+      REPO_ROOT="$2"; shift 2 ;;
+    --agent)
+      AGENT_ID="$2"; shift 2 ;;
+    --default-branch)
+      DEFAULT_BRANCH="$2"; shift 2 ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1 ;;
+  esac
+done
+
+if [[ -z "${REPO_ROOT}" || -z "${AGENT_ID}" ]]; then
+  echo "Usage: $0 --repo <memory-repo-path> --agent <agent-id> [--default-branch main]" >&2
+  exit 1
+fi
+
+if [[ ! -d "${REPO_ROOT}" ]]; then
+  echo "Repo path does not exist: ${REPO_ROOT}" >&2
+  exit 1
+fi
+
+if [[ ! -d "${REPO_ROOT}/.git" ]]; then
+  echo "Not a git repository: ${REPO_ROOT}" >&2
+  exit 1
+fi
+
+agent_dir="${REPO_ROOT}/agents/${AGENT_ID}"
+shared_dir="${REPO_ROOT}/shared"
+policy_dir="${REPO_ROOT}/policies"
+
+mkdir -p "${agent_dir}/inbox" \
+         "${agent_dir}/working" \
+         "${agent_dir}/handoff" \
+         "${agent_dir}/checkpoints" \
+         "${shared_dir}/announcements" \
+         "${shared_dir}/sop" \
+         "${policy_dir}"
+
+if [[ ! -f "${agent_dir}/AGENT-CARD.md" ]]; then
+cat > "${agent_dir}/AGENT-CARD.md" <<EOF
+# Agent Card: ${AGENT_ID}
+
+## Identity
+- agent_id: ${AGENT_ID}
+- default_branch: ${DEFAULT_BRANCH}
+
+## Writable Paths
+- agents/${AGENT_ID}/**
+- shared/announcements/**
+
+## Read-Only Preferred Paths
+- shared/sop/**
+- policies/**
+
+## Sync Rules
+1. Before write: git pull --rebase origin ${DEFAULT_BRANCH}
+2. After write: git add + git commit (small and atomic)
+3. Push immediately to reduce drift
+4. If conflict: auto-merge once, then manual resolve
+EOF
+fi
+
+if [[ ! -f "${agent_dir}/MEMORY-LOG.md" ]]; then
+cat > "${agent_dir}/MEMORY-LOG.md" <<EOF
+# ${AGENT_ID} Memory Log
+
+Append-only operational memory entries.
+EOF
+fi
+
+if [[ ! -f "${agent_dir}/PROMPT-RULES.md" ]]; then
+cat > "${agent_dir}/PROMPT-RULES.md" <<'EOF'
+# Prompt Rules
+
+- Always `git pull --rebase` before editing memory files.
+- Prefer appending new notes over editing old notes.
+- Commit frequently with narrow scope.
+- If rebase conflict occurs, try one automatic resolution, otherwise stop and ask for manual merge.
+EOF
+fi
+
+if [[ ! -f "${policy_dir}/WRITE-PERMISSIONS.yaml" ]]; then
+cat > "${policy_dir}/WRITE-PERMISSIONS.yaml" <<'EOF'
+version: 1
+rules:
+  - pattern: "agents/*/**"
+    write: ["owner"]
+  - pattern: "shared/announcements/**"
+    write: ["all_agents"]
+  - pattern: "shared/sop/**"
+    write: ["maintainers"]
+EOF
+fi
+
+if [[ ! -f "${REPO_ROOT}/README-memory-layout.md" ]]; then
+cat > "${REPO_ROOT}/README-memory-layout.md" <<'EOF'
+# Memory Repository Layout
+
+- agents/<agent-id>/ : private working memory
+- shared/announcements/ : multi-agent shared updates
+- shared/sop/ : stable SOP and rules
+- policies/ : write permission policy metadata
+EOF
+fi
+
+cd "${REPO_ROOT}"
+if ! git diff --quiet || ! git diff --cached --quiet; then
+  :
+fi
+
+echo "Scaffold created for agent '${AGENT_ID}' at ${agent_dir}"
+
+echo "Next steps:"
+echo "1) Review and adjust ${agent_dir}/AGENT-CARD.md"
+echo "2) git add agents/${AGENT_ID} shared policies README-memory-layout.md"
+echo "3) git commit -m 'chore: scaffold memory space for ${AGENT_ID}'"