Agent Communication Protocol (ACP) + Caveman Style v1 - token-efficient inter-agent comms

acp-caveman-v1.yaml

# Agent Communication Protocol (ACP) + Caveman Style - v1
# 
# Two layers: ACP handles structure (state transfer between agents),
# caveman handles style (brevity). Use together or separately.
#
# Author: Steven Gonsalvez (stevengonsalvez.com)
# Context: https://stevengonsalvez.com/byte-sized-banter/week-15-caveman-agent-language

agent_communication:
  version: "acp+caveman-v1"
  purpose: >
    Separate message structure from writing style.
    ACP handles state transfer.
    Caveman handles brevity and tone.

  layers:
    acp:
      type: "structure"
      applies_to: "agent_to_agent"
      goal: "state handoff with low ambiguity and low token use"
    caveman:
      type: "style"
      applies_to: "agent_to_agent + agent_to_human"
      goal: "terse, direct, low-fluff communication"

  routing:
    agent_to_agent:
      preferred_mode: "structured"
      fallback_mode: "natural"
    agent_to_human:
      preferred_mode: "natural"
      optional_style: "caveman"

  acp:
    enabled: true
    phase: "phase_1_optional"
    format:
      header_line: "[HEADER:value HEADER:value ...] [inbox:ID]"
      body: "1-3 sentences max"
    common_headers:
      - "PR:<num>"
      - "STATE:<OPEN|MERGED|CLOSED|DRAFT>"
      - "ACTION:<verb>"
      - "TARGET:<agent>"
      - "BLOCKER:<desc|none>"
      - "GATE:<gate>=<PASS|FAIL|PENDING>"
      - "ACK"
      - "ISSUE:<num>"
      - "BRANCH:<name>"
      - "PRIORITY:<level>"
    rules:
      - "headers carry state"
      - "body carries reasoning"
      - "do not restate headers in body"
      - "one message per logical action"
      - "if header and body conflict, header wins"
    loop_prevention:
      check_last_messages: 5
      no_reply_if:
        - "no new state added"
        - "another agent already posted equivalent state"
        - "message only repeats prior conclusion"

  caveman:
    enabled: true
    purpose: "short, technical, direct"
    rules:
      - "use fragments when clear"
      - "drop filler words"
      - "drop unnecessary politeness"
      - "prefer short exact words"
      - "keep technical terms exact"
      - "state thing -> action -> reason -> next step"
    pattern: "[thing] [action] [reason]. [next step]."
    avoid:
      - "great question"
      - "i'd be happy to help"
      - "absolutely"
      - "long preambles"
      - "hedging without narrowing"
    exceptions:
      - "security confirmations"
      - "irreversible action confirmations"
      - "sensitive human situations"

  combinations:
    - name: "acp_plus_caveman"
      use_when: "agent_to_agent work thread with state changes"
      example: >
        [PR:431 STATE:OPEN ACTION:review TARGET:splinter] [inbox:abc123]
        Arch ready. Need gate.
    - name: "caveman_only"
      use_when: "short status update, no structured state needed"
      example: "Inbox clean. No live debt. Detector false positive."
    - name: "natural_only"
      use_when: "human-facing explanation or nuanced conversation"
      example: >
        The structure rule is ACP. The terse style is caveman.
        They can be used together or separately.

  exemptions:
    thinking_out_loud:
      acp_required: false
      caveman_required: false
    human_context_heavy_messages:
      acp_required: false

  recommendation:
    default_agent_threads: "acp_plus_caveman"
    default_human_messages: "natural_or_caveman"