skill-system-comms

Skill System Comms

This skill is the merged owner of reviewer communication and coder lifecycle management. It replaces manual reviewer tmux messaging, ad-hoc inbox files, and split session-lifecycle ownership with one structured command surface.

Commands

bash "Work/.tkt/scripts/tmux-send-atom.sh" --key C-m <tmux-pane> <message>
bash "Work/.tkt/scripts/tmux-send-atom.sh" <tmux-pane> "/compact"
bash "Work/.tkt/scripts/tmux-send-atom.sh" --key Tab <tmux-pane>
bash "Work/.tkt/scripts/callosum.sh" render --meeting <meeting.md>
bash "Work/.tkt/scripts/callosum.sh" say --meeting <meeting.md> --speaker <wren|finch|lark> --message <message>
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/callosum.py" ensure-board [--board dev_user:callosum]
python3 "{skill_dir}/scripts/callosum.py" render --meeting <meeting.md> [--board dev_user:callosum]
python3 "{skill_dir}/scripts/callosum.py" say --meeting <meeting.md> --speaker <wren|finch|lark> --message <message>
python3 "{skill_dir}/scripts/reviewer_comms.py" dispatch-down <project> <session-type> <message> [--notify] [--escalation-level L0|L1|L2|L3] [--force --reason <text>]
python3 "{skill_dir}/scripts/reviewer_comms.py" startup <reviewer> [--message <context>]
python3 "{skill_dir}/scripts/reviewer_comms.py" session-report scan <project-dir>
python3 "{skill_dir}/scripts/coder_lifecycle.py" discover <project-dir>
python3 "{skill_dir}/scripts/coder_lifecycle.py" ensure <project-dir>
python3 "{skill_dir}/scripts/coder_lifecycle.py" cleanup <project-dir>
python3 "{skill_dir}/scripts/coder_lifecycle.py" restart <project-dir> <session-name>
python3 "{skill_dir}/scripts/coder_lifecycle.py" audit
bash "{skill_dir}/scripts/coder/dispatch-coder.sh" <tmux-pane> <message>
bash "{skill_dir}/scripts/coder/restart-coder.sh" <tmux-pane> [--session <id>] [--workdir <path>]
bash "{skill_dir}/scripts/coder/capture-coder.sh" <tmux-pane> [lines] [--todo]
bash "{skill_dir}/scripts/coder/health-check-coder.sh" [tmux-pane]
bash "{skill_dir}/scripts/coder/bootstrap-coders.sh" [SK|FD|EP ...]
bash "{skill_dir}/scripts/coder/coder-sessions.sh" [--get <keyword>]

Public CLI Wrapper

The thin public wrapper for coder harness commands is sk coder. The original shell scripts remain valid for backward compatibility.

python3 "{skill_dir}/../skill-system-cli/scripts/sk.py" coder dispatch dev_coder:SK-coder "B-069 TKT-001: implement wrapper"
python3 "{skill_dir}/../skill-system-cli/scripts/sk.py" coder capture dev_coder:SK-coder --lines 80 --todo
python3 "{skill_dir}/../skill-system-cli/scripts/sk.py" coder restart dev_coder:SK-coder --session ses_demo --workdir /tmp/project
python3 "{skill_dir}/../skill-system-cli/scripts/sk.py" coder sessions --get skills
python3 "{skill_dir}/../skill-system-cli/scripts/sk.py" coder health dev_coder:SK-coder
python3 "{skill_dir}/../skill-system-cli/scripts/sk.py" coder bootstrap SK FD

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>/.
• Same-level meetings use the corpus callosum path: callosum.py say appends the utterance to the meeting artifact, then renders the recent live log to dev_user:callosum.
• callosum.py render --meeting <meeting.md> refreshes the board without adding a new utterance.
• Editing a meeting artifact without a matching callosum live utterance is callosum bypass; acceptable for archival cleanup, not for active sister meeting turns.
• callosum.py ensure-board also attaches a pipe-pane audit log at .tkt/logs/callosum-pane.log; tmux scrollback is not durable evidence.
• Session-report reuses B-054 coder lifecycle discovery logic.
• tmux-send-atom.sh is the lowest-level tmux motor nerve: paste text and/or caller-specified key sequence only. Higher-level scripts compose it instead of open-coding load-buffer / paste-buffer / send-keys.
• compact-session.sh owns Codex/OpenCode self-compact gating: empty input + non-working pane + stable idle window, then bare /compact followed by independent C-m.
• dispatch-down rejects placeholder payloads and reports TASK/EXPECTED OUTCOME/CONTEXT quality.
• dispatch-down supports escalation levels L0-L3; L4 is intentionally unsupported.
• L1 prepends a status-check prefix without interrupting the coder pane.
• L2 invokes Work/.tkt/scripts/force-report-coder.sh, waits, then dispatches with an interruption prefix.
• L3 writes Hermes incident yaml + inbox artifacts before dispatching an emergency-prefixed message.
• Every L>=1 dispatch appends incident metadata under Work/.tkt/incidents/hermes/ and enforces level-specific cooldowns unless --force --reason is supplied.
• dispatch-down triggers architecture escalation metadata after three retryable failures.
• startup loads reviewer soul profile mappings from config/reviewer-comms.yaml.
• canonical coder/user/auto session discovery and mutation live in coder_lifecycle.py under this same skill.
• coder harness assets live under scripts/coder/ and remain reachable from Work/.tkt/scripts/ via symlink compatibility.

Example escalation calls:

python3 "{skill_dir}/scripts/reviewer_comms.py" dispatch-down ep coder "B-039 status?" --escalation-level L1
python3 "{skill_dir}/scripts/reviewer_comms.py" dispatch-down sk coder "force surface SK-C blocker" --escalation-level L2
python3 "{skill_dir}/scripts/reviewer_comms.py" dispatch-down fd coder "EMERGENCY: stop B-076 deploy" --escalation-level L3 --force --reason "production cluster freeze in flight"
python3 "{skill_dir}/scripts/reviewer_comms.py" dispatch-down sk coder "self test" --self-test

Cooldown windows:

• L1: max 1 invocation per target per 30 minutes
• L2: max 1 invocation per target per 60 minutes
• L3: max 1 invocation per target per 24 hours and requires prior L1/L2 attempts unless bypassed
• --force bypasses cooldown only when paired with --reason "...", and the bypass is logged in the incident yaml

Intentional limit:

• L4 is not implemented. The escalation ladder stops at L3 by design.

{
  "schema_version": "2.0",
  "id": "skill-system-comms",
  "version": "1.1.0",
  "capabilities": ["reviewer-send", "reviewer-broadcast", "reviewer-ack", "reviewer-poll", "reviewer-meeting", "reviewer-callosum", "reviewer-dispatch-down", "reviewer-startup", "reviewer-session-report", "session-discover", "session-ensure", "session-cleanup", "session-restart", "session-audit", "coder-harness"],
  "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.",
      "input": {
        "subcommand": {"type": "string", "required": true, "description": "start/ack/status/close"}
      },
      "output": {
        "description": "Meeting operation result",
        "fields": {"meeting_id": "string"}
      },
      "entrypoints": {
        "agent": "Invoke reviewer_comms.py meeting start|ack|status|close with required args"
      }
    },
    "dispatch-down": {
      "description": "Dispatch work context to a downstream opencode session with placeholder guards, escalation levels, and cooldown-aware incident logging.",
      "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"},
        "escalation_level": {"type": "string", "required": false, "description": "L0|L1|L2|L3 escalation level"},
        "force": {"type": "boolean", "required": false, "description": "Bypass cooldown when accompanied by reason"},
        "reason": {"type": "string", "required": false, "description": "Required justification when force=true"}
      },
      "output": {
        "description": "Dispatch result with prompt-quality metadata",
        "fields": {"session_id": "string", "prompt_quality": "object", "escalation_level": "string", "incident_path": "string"}
      },
      "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>"
      }
    },
    "discover": {
      "description": "Discover canonical coder/user/auto sessions for one project.",
      "input": {
        "project_dir": {"type": "string", "required": true, "description": "Target project directory"}
      },
      "output": {
        "description": "Canonical session status plus extras",
        "fields": {"sessions": "array", "extras": "array"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/coder_lifecycle.py", "discover", "{project_dir}"]
      }
    },
    "ensure": {
      "description": "Ensure canonical coder/user/auto sessions exist for one project.",
      "input": {
        "project_dir": {"type": "string", "required": true, "description": "Target project directory"}
      },
      "output": {
        "description": "Created sessions and final state",
        "fields": {"created": "array", "sessions": "array"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/coder_lifecycle.py", "ensure", "{project_dir}"]
      }
    },
    "cleanup": {
      "description": "Delete non-canonical sessions from one project.",
      "input": {
        "project_dir": {"type": "string", "required": true, "description": "Target project directory"}
      },
      "output": {
        "description": "Deleted extra sessions and final state",
        "fields": {"deleted": "array", "sessions": "array"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/coder_lifecycle.py", "cleanup", "{project_dir}"]
      }
    },
    "restart": {
      "description": "Restart one canonical session for a project.",
      "input": {
        "project_dir": {"type": "string", "required": true, "description": "Target project directory"},
        "session_name": {"type": "string", "required": true, "description": "Canonical session name"}
      },
      "output": {
        "description": "Restart result and final state",
        "fields": {"restarted": "boolean", "sessions": "array"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/coder_lifecycle.py", "restart", "{project_dir}", "{session_name}"]
      }
    },
    "audit": {
      "description": "Audit all known projects for session health.",
      "input": {},
      "output": {
        "description": "Session health rows by project",
        "fields": {"rows": "array"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/coder_lifecycle.py", "audit"]
      }
    },
    "dispatch-coder": {
      "description": "Send a message to a coder tmux pane and submit it.",
      "input": {
        "pane": {"type": "string", "required": true},
        "message": {"type": "string", "required": true}
      },
      "output": {
        "description": "Dispatch result",
        "fields": {"status": "string"}
      },
      "entrypoints": {
        "unix": ["bash", "{skill_dir}/scripts/coder/dispatch-coder.sh", "{pane}", "{message}"]
      }
    },
    "restart-coder": {
      "description": "Kill and restart opencode in a coder pane, optionally resuming a specific session.",
      "input": {
        "pane": {"type": "string", "required": true},
        "session_id": {"type": "string", "required": false},
        "workdir": {"type": "string", "required": false}
      },
      "output": {
        "description": "Restart status",
        "fields": {"status": "string"}
      },
      "entrypoints": {
        "agent": "Invoke scripts/coder/restart-coder.sh with pane and optional --session/--workdir flags"
      }
    },
    "capture-coder": {
      "description": "Capture and clean coder TUI output.",
      "input": {
        "pane": {"type": "string", "required": true},
        "lines": {"type": "integer", "required": false},
        "todo_mode": {"type": "boolean", "required": false}
      },
      "output": {
        "description": "Cleaned capture output",
        "fields": {"capture": "string"}
      },
      "entrypoints": {
        "agent": "Invoke scripts/coder/capture-coder.sh with pane, optional line count, and optional --todo"
      }
    },
    "health-check-coder": {
      "description": "Check coder process and todo progress health.",
      "input": {
        "pane": {"type": "string", "required": false}
      },
      "output": {
        "description": "Health report",
        "fields": {"report": "string"}
      },
      "entrypoints": {
        "agent": "Invoke scripts/coder/health-check-coder.sh with optional pane"
      }
    },
    "bootstrap-coders": {
      "description": "Create dev_coder tmux windows and start or resume coder sessions.",
      "input": {
        "targets": {"type": "array", "required": false}
      },
      "output": {
        "description": "Bootstrap report",
        "fields": {"status": "string"}
      },
      "entrypoints": {
        "agent": "Invoke scripts/coder/bootstrap-coders.sh with optional target names"
      }
    },
    "coder-sessions": {
      "description": "List or resolve opencode session ids for coder panes.",
      "input": {
        "query": {"type": "string", "required": false}
      },
      "output": {
        "description": "Session list or matched session id",
        "fields": {"result": "string"}
      },
      "entrypoints": {
        "agent": "Invoke scripts/coder/coder-sessions.sh with optional --get <query>"
      }
    }
  },
  "stdout_contract": {
    "last_line_json": true
  }
}