skill-system-reviewer-comms

What this skill does

# Skill System Reviewer Comms

This skill replaces manual reviewer tmux messaging and ad-hoc inbox files with a
structured command surface.

## Commands

```bash
python3 "{skill_dir}/scripts/reviewer_comms.py" send <target> <message>
python3 "{skill_dir}/scripts/reviewer_comms.py" broadcast <message>
python3 "{skill_dir}/scripts/reviewer_comms.py" ack <message-id>
python3 "{skill_dir}/scripts/reviewer_comms.py" poll
python3 "{skill_dir}/scripts/reviewer_comms.py" meeting start <topic>
python3 "{skill_dir}/scripts/reviewer_comms.py" meeting ack <meeting-id> <reviewer>
python3 "{skill_dir}/scripts/reviewer_comms.py" meeting status <meeting-id>
python3 "{skill_dir}/scripts/reviewer_comms.py" meeting close <meeting-id>
python3 "{skill_dir}/scripts/reviewer_comms.py" meeting agenda add <topic> --author <name> --kind vote|discuss --text <item>
python3 "{skill_dir}/scripts/reviewer_comms.py" meeting agenda list <topic>
python3 "{skill_dir}/scripts/reviewer_comms.py" meeting veto <meeting-id> --item-id <id> --author <name> --reason <text>
python3 "{skill_dir}/scripts/reviewer_comms.py" meeting veto-list <meeting-id>
python3 "{skill_dir}/scripts/reviewer_comms.py" dispatch-down <project> <session-type> <message> [--notify]
python3 "{skill_dir}/scripts/reviewer_comms.py" startup <reviewer> [--message <context>]
python3 "{skill_dir}/scripts/reviewer_comms.py" session-report scan <project-dir>
```

## Rules

- tmux routing is by window name under `dev-user:<target>`.
- Message and ack artifacts are file-backed under `.tkt/`.
- Meeting close emits per-owner inbox YAML under `.tkt/inbox/<reviewer>/`.
- Meeting agenda: any participant may pre-file items (`meeting agenda add`) before `meeting start` consumes them into the meeting md. Items are either `vote` or `discuss`.
- Absolute veto: any single participant may veto one agenda item (`meeting veto`) with a mandatory reason. The item is flagged `redraft_required` and the meeting continues for the remaining items — no quorum needed. Authority: Arthur 2026-04-13 directive.
- Session-report reuses B-054 coder lifecycle discovery logic.
- dispatch-down rejects placeholder payloads and reports TASK/EXPECTED OUTCOME/CONTEXT quality.
- dispatch-down triggers architecture escalation metadata after three retryable failures.
- startup loads reviewer soul profile mappings from `config/reviewer-comms.yaml`.

```skill-manifest
{
  "schema_version": "2.0",
  "id": "skill-system-reviewer-comms",
  "version": "1.1.0",
  "capabilities": ["reviewer-send", "reviewer-broadcast", "reviewer-ack", "reviewer-poll", "reviewer-meeting", "reviewer-meeting-agenda", "reviewer-meeting-veto", "reviewer-dispatch-down", "reviewer-startup", "reviewer-session-report"],
  "effects": ["fs.read", "fs.write", "proc.exec", "db.read"],
  "operations": {
    "send": {
      "description": "Send a reviewer message to one named reviewer window and log it.",
      "input": {
        "target": {"type": "string", "required": true, "description": "Reviewer window target"},
        "message": {"type": "string", "required": true, "description": "Message body"}
      },
      "output": {
        "description": "Delivery result and message id",
        "fields": {"message_id": "string", "delivery": "object"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/reviewer_comms.py", "send", "{target}", "{message}"]
      }
    },
    "broadcast": {
      "description": "Send a reviewer message to all known reviewer windows.",
      "input": {
        "message": {"type": "string", "required": true, "description": "Message body"}
      },
      "output": {
        "description": "Per-target delivery rows",
        "fields": {"rows": "array"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/reviewer_comms.py", "broadcast", "{message}"]
      }
    },
    "ack": {
      "description": "Acknowledge a reviewer message.",
      "input": {
        "message_id": {"type": "string", "required": true, "description": "Message id"}
      },
      "output": {
        "description": "Ack result",
        "fields": {"ack_path": "string", "ack_at": "string"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/reviewer_comms.py", "ack", "{message_id}"]
      }
    },
    "poll": {
      "description": "List sent reviewer messages with ack status.",
      "input": {},
      "output": {
        "description": "Poll rows",
        "fields": {"rows": "array"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/reviewer_comms.py", "poll"]
      }
    },
    "meeting": {
      "description": "Manage reviewer meeting lifecycle including pre-filed agenda items and per-item absolute veto.",
      "input": {
        "subcommand": {"type": "string", "required": true, "description": "start/ack/status/close/agenda/veto/veto-list"}
      },
      "output": {
        "description": "Meeting operation result",
        "fields": {"meeting_id": "string", "agenda_consumed_path": "string", "redraft_required": "boolean"}
      },
      "entrypoints": {
        "agent": "Invoke reviewer_comms.py meeting {start|ack|status|close|agenda add|agenda list|veto|veto-list} with required args. Agenda items (kind=vote|discuss) are pre-filed by any participant; a single veto with reason marks an item redraft_required and the meeting continues for remaining items."
      }
    },
    "dispatch-down": {
      "description": "Dispatch work context to a downstream opencode session with placeholder and prompt-quality guards.",
      "input": {
        "project_alias": {"type": "string", "required": true, "description": "Project alias fd|ep|sk"},
        "session_type": {"type": "string", "required": true, "description": "Session lane"},
        "message": {"type": "string", "required": true, "description": "Dispatch payload"},
        "notify": {"type": "boolean", "required": false, "description": "Notification-only dispatch"}
      },
      "output": {
        "description": "Dispatch result with prompt-quality metadata",
        "fields": {"session_id": "string", "prompt_quality": "object"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/reviewer_comms.py", "dispatch-down", "{project_alias}", "{session_type}", "{message}"]
      }
    },
    "startup": {
      "description": "Load reviewer soul profile and deliver startup payload.",
      "input": {
        "reviewer": {"type": "string", "required": true, "description": "Reviewer identity"},
        "message": {"type": "string", "required": false, "description": "Optional startup context"}
      },
      "output": {
        "description": "Startup delivery payload with profile metadata",
        "fields": {"profile_name": "string", "profile_path": "string", "inbox_path": "string"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/reviewer_comms.py", "startup", "{reviewer}"]
      }
    },
    "session-report": {
      "description": "Scan project sessions and emit per-session summaries.",
      "input": {
        "project_dir": {"type": "string", "required": true, "description": "Target project directory"}
      },
      "output": {
        "description": "Session report rows and auto report payloads",
        "fields": {"rows": "array", "auto_reports": "array"}
      },
      "entrypoints": {
        "agent": "Invoke reviewer_comms.py session-report scan <project-dir>"
      }
    }
  },
  "stdout_contract": {
    "last_line_json": true
  }
}
```