enhance hcom-agent-messaging skill + add hcom-workflow-scripts skill by yigitkonur · Pull Request #17 · aannoo/hcom

yigitkonur · 2026-03-24T13:37:24Z

what this does

enhances the existing hcom-agent-messaging skill and adds a new hcom-workflow-scripts skill — both built from hands-on testing with real claude + codex agents.

hcom-agent-messaging (enhanced)

the existing skill was a solid setup/troubleshooting guide. this PR keeps the original name and description but adds practical depth:

tested command reference with real timing data (claude <1s delivery, codex 1-3s)
per-tool delivery details — how hooks work for claude (10 hooks), gemini (7), codex (1 notify + PTY injection), opencode (plugin)
scripting patterns section with working code examples
intent system docs — request/inform/ack and how agents respond to each
codex session binding gotchas — the 5-10s binding delay, stale_cleanup, and the fix (hcom events --wait 30 --idle $name)
4 new reference docs: patterns.md, cli-reference.md, cross-tool.md, gotchas.md

hcom-workflow-scripts (new skill)

a new skill focused on writing custom multi-agent workflow scripts. includes:

script template with annotated commentary explaining every convention
6 tested scripts — all verified with real agent runs:
- basic two-agent messaging (claude x2, ~17s)
- worker-reviewer feedback loop (claude x2, ~20s)
- cross-tool duo — claude designs spec, codex implements (claude+codex, ~30s)
- ensemble consensus — 3 agents + judge (claude x4, ~30s)
- cascade pipeline — sequential plan→execute with transcript handoff (claude x2, ~25s)
- codex worker — codex writes code, claude reviews transcript (codex+claude, ~35s)
agent topology guide — worker-reviewer, pipeline, ensemble, hub-spoke, reactive
architecture reference — db schema, hook system, delivery pipeline, event subscriptions
cross-tool scripting guide — claude vs codex quirks, timing data, session binding differences
debugging reference — stale agents, message delivery failures, codex binding issues

how this was tested

all 6 scripts were run with real hcom v0.7.6 agents. each test launched headless claude and/or codex agents, exchanged messages via threads, and verified completion signals via hcom events --wait --sql. real event JSON from test runs is included in the pattern docs.

test results:

pattern	agents	tools	result	time
basic messaging	2	claude x2	pass	~17s
review loop	2	claude x2	pass	~20s
cross-tool duo	2	claude+codex	pass	~30s
ensemble consensus	4	claude x4	pass	~30s
cascade pipeline	2	claude x2	pass	~25s
codex→claude review	2	codex+claude	pass	~35s

files changed

skills/hcom-agent-messaging/SKILL.md          (enhanced: 140→302 lines)
skills/hcom-agent-messaging/references/        (4 new docs, 1253 lines total)
skills/hcom-workflow-scripts/SKILL.md          (new: 154 lines)
skills/hcom-workflow-scripts/references/        (5 docs + 6 scripts, 2050 lines total)

17 files changed, 3377 insertions, 66 deletions.

enhanced the existing hcom-agent-messaging skill with: - tested command reference with real timing data - per-tool delivery details (claude <1s, codex 1-3s) - scripting patterns section with working examples - 4 reference docs (patterns, cli-reference, cross-tool, gotchas) - intent system documentation - codex session binding gotchas added new hcom-workflow-scripts skill for building multi-agent workflows: - 6 tested scripts (basic messaging, review loop, cross-tool duo, ensemble consensus, cascade pipeline, codex-worker) - all scripts tested with real claude + codex agents (6/6 passed) - architecture reference (db schema, hooks, delivery pipeline) - script template with annotated commentary - agent topology guide (worker-reviewer, pipeline, ensemble, hub-spoke, reactive) - cross-tool scripting guide (claude + codex quirks, timing data) - debugging reference (stale agents, message delivery, codex binding)

Copilot

Pull request overview

This PR expands the existing hcom-agent-messaging skill with more tested, tool-specific operational guidance and adds a new hcom-workflow-scripts skill focused on authoring and running multi-agent orchestration scripts (with references and runnable examples).

Changes:

Enhanced hcom-agent-messaging with a quick-reference command section plus new deep-dive reference docs (CLI reference, patterns, cross-tool notes, gotchas).
Added new hcom-workflow-scripts skill with architecture/debugging/pattern references and a script template.
Added 6 runnable workflow script examples (basic messaging, review loop, ensemble consensus, cascade pipeline, cross-tool duo, codex worker).

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 18 comments.

Show a summary per file

File	Description
skills/hcom-workflow-scripts/SKILL.md	New skill entrypoint and overview for workflow scripting patterns and references
skills/hcom-workflow-scripts/references/architecture.md	hcom internal architecture reference (DB schema, routing, lifecycle, delivery pipeline)
skills/hcom-workflow-scripts/references/cross-tool-scripting.md	Cross-tool behavior notes (Claude/Codex/Gemini/OpenCode) and timing/binding guidance
skills/hcom-workflow-scripts/references/debugging.md	Troubleshooting guide for script hangs, delivery failures, stale cleanup, etc.
skills/hcom-workflow-scripts/references/patterns.md	Tested multi-agent patterns with example scripts and sample event JSON
skills/hcom-workflow-scripts/references/script-template.md	Annotated script template and conventions for safe orchestration scripts
skills/hcom-workflow-scripts/references/scripts/basic-messaging.sh	Example script: two-agent messaging + DONE signal
skills/hcom-workflow-scripts/references/scripts/review-loop.sh	Example script: worker/reviewer feedback loop until approval
skills/hcom-workflow-scripts/references/scripts/ensemble-consensus.sh	Example script: 3 contestants + judge fan-out/fan-in
skills/hcom-workflow-scripts/references/scripts/cascade-pipeline.sh	Example script: sequential plan → execute pipeline using transcript handoff
skills/hcom-workflow-scripts/references/scripts/cross-tool-duo.sh	Example script: Claude spec → Codex implementation cross-tool workflow
skills/hcom-workflow-scripts/references/scripts/codex-worker.sh	Example script: Codex codes, Claude reviews transcript
skills/hcom-agent-messaging/SKILL.md	Updated skill guide with essential commands, tool support matrix, and scripting patterns
skills/hcom-agent-messaging/references/patterns.md	Multi-agent patterns reference (tested examples + event JSON)
skills/hcom-agent-messaging/references/cli-reference.md	CLI command/flag reference for launches, messaging, events, transcripts, scripts, config
skills/hcom-agent-messaging/references/cross-tool.md	Cross-tool collaboration behavior and binding/delivery gotchas
skills/hcom-agent-messaging/references/gotchas.md	Script gotchas and operational troubleshooting guidance

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-24T13:45:44Z

skills/hcom-workflow-scripts/references/scripts/review-loop.sh

+echo "Thread: $thread"
+echo "Waiting..."
+
+hcom events --wait 120 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%FINAL%'" $name_arg >/dev/null 2>&1 && echo "PASS" || echo "FAIL"


hcom events --wait ... is used as a boolean with output redirected away. Given the repo’s docs (in this same PR) that hcom events --wait returns exit code 0 on both match and timeout, this will always print PASS. Capture output and check for empty/non-empty to correctly detect whether FINAL arrived.

Suggested change

hcom events --wait 120 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%FINAL%'" $name_arg >/dev/null 2>&1 && echo "PASS" || echo "FAIL"

final_events=$(hcom events --wait 120 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%FINAL%'" $name_arg 2>/dev/null)

if [[ -n "$final_events" ]]; then

echo "PASS"

else

echo "FAIL"

fi

Copilot · 2026-03-24T13:45:45Z

skills/hcom-workflow-scripts/references/scripts/review-loop.sh

+cleanup() {
+  for name in "${LAUNCHED_NAMES[@]}"; do
+    hcom kill "$name" --go 2>/dev/null || true
+  done


The script parses --name into name_arg but doesn’t pass it through to the launch/kill calls. If these scripts are intended for hcom run, this can cause hcom subcommands to fail to identify the caller. Forward $name_arg to all hcom invocations (including cleanup).

Copilot · 2026-03-24T13:45:45Z

skills/hcom-workflow-scripts/references/scripts/cascade-pipeline.sh

+trap cleanup ERR
+


trap cleanup ERR won’t run if the script exits explicitly (e.g., exit 1) or is interrupted (SIGINT/SIGTERM). Since this script can exit 1 on timeouts, it can leave headless agents orphaned. Consider trapping EXIT (and optionally INT/TERM) to ensure cleanup always runs, and keep ERR if you still want early cleanup on failing commands.

Copilot · 2026-03-24T13:45:46Z

skills/hcom-workflow-scripts/references/scripts/cross-tool-duo.sh

+launch_out=$(hcom 1 claude --tag arch --go --headless \
+  --hcom-prompt "Design a 2-3 sentence spec for: ${task}. Send to @eng-: hcom send \"@eng-\" --thread ${thread} --intent request -- \"SPEC: <spec>\". Wait for confirmation. Then send: hcom send \"@bigboss\" --thread ${thread} --intent inform -- \"APPROVED\". Then stop: hcom stop" 2>&1)
+track_launch "$launch_out"
+arch=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
+echo "Architect (Claude): $arch"
+
+launch_out=$(hcom 1 codex --tag eng --go --headless \
+  --hcom-prompt "Wait for spec from @arch-. Implement it. Then confirm: hcom send \"@${arch}\" --thread ${thread} --intent inform -- \"IMPLEMENTED\". Then stop: hcom stop" 2>&1)
+track_launch "$launch_out"
+eng=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
+echo "Engineer (Codex): $eng"


Cross-tool scripts are documented elsewhere in this PR as requiring an hcom events --wait ... --idle "$codex_name" wait before any messages are sent to Codex. Here, Claude is launched first and will likely send the SPEC immediately, before the Codex session binds, which can cause the spec message to be dropped or never delivered. Reorder to launch Codex first (and wait for idle) or add an explicit idle/binding wait before Claude sends the SPEC.

Suggested change

launch_out=$(hcom 1 claude --tag arch --go --headless \

--hcom-prompt "Design a 2-3 sentence spec for: ${task}. Send to @eng-: hcom send \"@eng-\" --thread ${thread} --intent request -- \"SPEC: <spec>\". Wait for confirmation. Then send: hcom send \"@bigboss\" --thread ${thread} --intent inform -- \"APPROVED\". Then stop: hcom stop" 2>&1)

track_launch "$launch_out"

arch=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')

echo "Architect (Claude): $arch"

launch_out=$(hcom 1 codex --tag eng --go --headless \

--hcom-prompt "Wait for spec from @arch-. Implement it. Then confirm: hcom send \"@${arch}\" --thread ${thread} --intent inform -- \"IMPLEMENTED\". Then stop: hcom stop" 2>&1)

track_launch "$launch_out"

eng=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')

echo "Engineer (Codex): $eng"

launch_out=$(hcom 1 codex --tag eng --go --headless \

--hcom-prompt "Wait for spec from @arch-. Implement it. Then confirm: hcom send \"@arch-\" --thread ${thread} --intent inform -- \"IMPLEMENTED\". Then stop: hcom stop" 2>&1)

track_launch "$launch_out"

eng=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')

echo "Engineer (Codex): $eng"

# Ensure Codex is fully bound and idle before Claude can send it any messages.

hcom events --wait 180 --idle "${eng}" $name_arg >/dev/null 2>&1

launch_out=$(hcom 1 claude --tag arch --go --headless \

--hcom-prompt "Design a 2-3 sentence spec for: ${task}. Send to @eng-: hcom send \"@eng-\" --thread ${thread} --intent request -- \"SPEC: <spec>\". Wait for confirmation. Then send: hcom send \"@bigboss\" --thread ${thread} --intent inform -- \"APPROVED\". Then stop: hcom stop" 2>&1)

track_launch "$launch_out"

arch=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')

echo "Architect (Claude): $arch"

Copilot · 2026-03-24T13:45:46Z

skills/hcom-workflow-scripts/references/scripts/ensemble-consensus.sh

+for i in 1 2 3; do
+  launch_out=$(hcom 1 claude --tag "c${i}" --go --headless \
+    --hcom-prompt "Answer: ${task}. Send ONLY your answer: hcom send \"@judge-\" --thread ${thread} --intent inform -- \"C${i}: <answer>\". Then stop: hcom stop" 2>&1)
+  track_launch "$launch_out"
+  name=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
+  echo "Contestant $i: $name"
+done
+
+launch_out=$(hcom 1 claude --tag judge --go --headless \
+  --hcom-prompt "Wait for 3 answers in thread '${thread}'. Check: hcom events --sql \"msg_thread='${thread}'\" --last 10. Pick best. Send: hcom send \"@bigboss\" --thread ${thread} --intent inform -- \"VERDICT: <winner>\". Then stop: hcom stop" 2>&1)


The --name flag is parsed into name_arg, but it isn’t forwarded to the hcom commands in this script besides the events --wait. If these scripts are expected to work via hcom run (which injects --name), propagate $name_arg to all hcom calls (launch, kill, events queries) for consistent identity resolution.

Copilot · 2026-03-24T13:45:49Z

skills/hcom-workflow-scripts/references/scripts/basic-messaging.sh

+launch_out=$(hcom 1 claude --tag worker --go --headless \
+  --hcom-prompt "Do this: ${task}. Send result to @reviewer- via: hcom send \"@reviewer-\" --thread ${thread} --intent inform -- \"RESULT: <your answer>\". Then stop: hcom stop" 2>&1)
+track_launch "$launch_out"
+worker=$(echo "$launch_out" | grep '^Names: ' | sed 's/^Names: //' | tr -d ' ')
+echo "Worker: $worker"
+
+launch_out=$(hcom 1 claude --tag reviewer --go --headless \
+  --hcom-prompt "Wait for a message from @worker-. When received, reply: hcom send \"@${worker}\" --thread ${thread} --intent ack -- \"ACK: received\". Then send: hcom send \"@bigboss\" --thread ${thread} --intent inform -- \"DONE\". Then stop: hcom stop" 2>&1)


The script parses --name into name_arg, but most hcom invocations (launches, kills, final events --sql) don’t include it. If this is run via hcom run (which injects --name), those commands may not resolve the caller identity consistently. Pass $name_arg through to all hcom commands in the script (including kill in cleanup).

Copilot · 2026-03-24T13:45:49Z

skills/hcom-workflow-scripts/references/scripts/cascade-pipeline.sh

+echo "Waiting for plan..."
+hcom events --wait 60 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%PLAN DONE%'" $name_arg >/dev/null 2>&1 || { echo "FAIL (planner timeout)"; exit 1; }
+


hcom events --wait ... is used as a boolean (and stdout is discarded), but this repository’s docs state hcom events --wait returns exit code 0 on both match and timeout. That means the planner timeout branch won’t trigger and failures may be reported as PASS. Capture the output and check whether it is empty to detect timeouts reliably.

Copilot · 2026-03-24T13:45:49Z

skills/hcom-workflow-scripts/references/scripts/cross-tool-duo.sh

+echo "Thread: $thread"
+echo "Waiting..."
+
+hcom events --wait 180 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%APPROVED%'" $name_arg >/dev/null 2>&1 && echo "PASS" || echo "FAIL"


hcom events --wait ... is used as a boolean with output discarded. This PR’s own debugging docs state hcom events --wait returns exit code 0 on both match and timeout, so this will always print PASS. Capture the output and test for empty/non-empty to distinguish match vs timeout.

Suggested change

hcom events --wait 180 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%APPROVED%'" $name_arg >/dev/null 2>&1 && echo "PASS" || echo "FAIL"

events_out=$(hcom events --wait 180 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%APPROVED%'" $name_arg 2>/dev/null || true)

if [[ -n "$events_out" ]]; then

echo "PASS"

else

echo "FAIL"

fi

Copilot · 2026-03-24T13:45:49Z

skills/hcom-workflow-scripts/references/scripts/codex-worker.sh

+trap - ERR
+for name in "${LAUNCHED_NAMES[@]}"; do hcom kill "$name" --go 2>/dev/null || true; done
+hcom events --sql "msg_thread='${thread}'" --last 10 2>&1


The script parses --name into name_arg, but most hcom invocations don’t include it (launches, kills, final events --sql). If the script is run under hcom run, this can break identity resolution for those commands. Pass $name_arg to all hcom commands for consistency.

Copilot · 2026-03-24T13:45:50Z

skills/hcom-workflow-scripts/references/scripts/ensemble-consensus.sh

+echo "Thread: $thread"
+echo "Waiting..."
+
+hcom events --wait 120 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%VERDICT%'" $name_arg >/dev/null 2>&1 && echo "PASS" || echo "FAIL"


hcom events --wait ... is treated as a success/failure boolean with stdout discarded. This PR’s debugging docs say the exit code is 0 on both match and timeout, so this will always print PASS and won’t detect timeouts. Capture the output and check for non-empty instead of relying on the exit status.

Suggested change

hcom events --wait 120 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%VERDICT%'" $name_arg >/dev/null 2>&1 && echo "PASS" || echo "FAIL"

events_out=$(hcom events --wait 120 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%VERDICT%'" $name_arg 2>/dev/null)

if [[ -n "$events_out" ]]; then

echo "PASS"

else

echo "FAIL"

fi

- events --wait returns 0/1/2 (match/timeout/SQL error), not 0 for both - stale cleanup threshold is 120s not 30s (CLEANUP_PLACEHOLDER_THRESHOLD) - cross-tool-duo.sh: launch Codex first and wait for idle before Claude sends spec — avoids race where spec arrives before session binds - trap cleanup ERR INT TERM in all scripts (was ERR-only, missing signals) Co-authored-by: Yigit Konur <9989650+yigitkonur@users.noreply.github.com>

Copilot AI review requested due to automatic review settings March 24, 2026 13:37

Copilot started reviewing on behalf of yigitkonur March 24, 2026 13:37 View session

Copilot AI reviewed Mar 24, 2026

View reviewed changes

aannoo merged commit eaead1a into aannoo:main Mar 27, 2026
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

enhance hcom-agent-messaging skill + add hcom-workflow-scripts skill#17

enhance hcom-agent-messaging skill + add hcom-workflow-scripts skill#17
aannoo merged 2 commits intoaannoo:mainfrom
yigitkonur:enhance-skills

yigitkonur commented Mar 24, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 24, 2026

Uh oh!

Copilot AI Mar 24, 2026

Uh oh!

Copilot AI Mar 24, 2026

Uh oh!

Copilot AI Mar 24, 2026

Uh oh!

Copilot AI Mar 24, 2026

Uh oh!

Copilot AI Mar 24, 2026

Uh oh!

Copilot AI Mar 24, 2026

Uh oh!

Copilot AI Mar 24, 2026

Uh oh!

Copilot AI Mar 24, 2026

Uh oh!

Copilot AI Mar 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		echo "Waiting for plan..."
		hcom events --wait 60 --sql "type='message' AND msg_thread='${thread}' AND msg_text LIKE '%PLAN DONE%'" $name_arg >/dev/null 2>&1 \|\| { echo "FAIL (planner timeout)"; exit 1; }

Conversation

yigitkonur commented Mar 24, 2026

what this does

hcom-agent-messaging (enhanced)

hcom-workflow-scripts (new skill)

how this was tested

files changed

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants