darwin-comms

name	darwin-comms
description	Report findings and status updates to the Darwin FRIDAY. Use team_send_results for final reports (task modes). In message mode, use team_send_message instead.
roles	["architect","sysadmin","developer","qe"]

Communicating with the Darwin FRIDAY

Staying Current with the Blackboard

Call bb_catch_up at the START of every task to see what happened since your last involvement. The blackboard shows turns from other agents, FRIDAY decisions, and user messages.

During long-running tasks, the PostToolUse hook automatically surfaces new turns. If you see a "Blackboard update" in your context, acknowledge and adapt.

Querying Service Context

Use svc_get_journal instead of relying on the event document for ops history. The event document is a dispatch-time snapshot; the journal MCP provides real-time data.

Use svc_get_service to check current service metrics (CPU, memory, error rate, replicas) before making recommendations.

Additional evidence sources are available: K8s MCP (remote clusters), ArgoCD MCP (local cluster), Playwright MCP (browser). Include relevant findings in your report.

team_send_results -- Final Report (task modes)

Use team_send_results to deliver your final report in task modes (execute, investigate, plan, implement, test). In message mode, team_send_results is not available -- use team_send_message to update FRIDAY instead.

FRIDAY uses your last team_send_results call as your final deliverable.

• Each call overwrites the previous result (last-write-wins). FRIDAY receives only the last call.

• Call team_send_results before finishing your task with your final summary.

• Structure your report with YAML frontmatter (required by team_send_results):

  ---
  reasoning: "one-sentence root cause (specific error condition, not a status label)"
  steps:
    - id: check-pac-controller
      agent: sysadmin
      summary: "Check PaC controller pod health on Konflux cluster"
    - id: retrigger-webhook
      agent: developer
      summary: "An empty commit may retrigger the webhook — requires FRIDAY approval as a branch mutation"
  ---
  
  ## Investigation Report
  
  (narrative evidence, log excerpts, timeline, what you observed)
  

• reasoning (required): the root cause. team_send_results rejects without it.

• steps (optional): remediation proposals for FRIDAY to evaluate. FRIDAY decides whether to dispatch, approve, or escalate based on the source mutation approval gate. Each step needs id, agent, summary. Omit if no further action needed.

Evidence Quality

Your report must contain at least one observable condition -- a specific error message, log excerpt, exit code, or concrete resource state. Status labels alone ("pipeline failed", "pod unhealthy") are insufficient. If you cannot extract the specific error, state what you tried and what blocked you (pruned logs, permission denied, external system).

team_send_message -- Send a progress note (all modes)

Progress notes appear in FRIDAY's UI. They do not replace your deliverable.

Use for status updates, phase transitions, or interim observations during long-running tasks. Available in all modes including message mode (where it is the primary FRIDAY communication tool).

team_check_messages -- Poll for incoming messages

Messages from FRIDAY and teammates are delivered automatically via CLI hooks. If automatic delivery doesn't fire, call team_check_messages between work phases.

Shell Fallback

Shell scripts sendResults, sendMessage are available as fallback if MCP tools fail.

Long-Running Operations -- NEVER Poll

If your action triggers a long-running process (CI/CD pipelines, ArgoCD syncs, image builds):

1. Execute the action (post /retest, trigger pipeline, push commit)
2. Confirm it was accepted (pipeline status changed to running)
3. Return immediately with current state and YAML frontmatter (reasoning: current state description)

NEVER poll, sleep, or loop waiting for completion. FRIDAY manages all wait cycles and timing.

Workflow (all modes)

1. team_send_message -- "Starting investigation..."
2. ... do work ...
3. team_send_message -- "Found root cause"
4. ... apply fix ...
5. team_send_results -- Final report with YAML frontmatter (reasoning required) and narrative evidence body