agmsg-orchestration

agmsg orchestration

Use this skill for structured multi-agent work where a Claude Code orchestrator assigns bounded tasks to Codex workers through agmsg teams. Use the regular agmsg skill for simple send/inbox/history commands.

Architecture

• Claude Code is the orchestrator: it writes task files, starts workers, reviews artifacts, and sends acceptance or revision messages.
• Codex workers execute one assigned task: they read the task file, obey file and action constraints, write artifacts, and send the required result message.
• agmsg is the message bus. Use only scripts under ~/.agents/skills/agmsg/scripts/.
• herdr panes are optional worker terminals; they are a launch surface, not the protocol.
• This skill adopts only the Hermes Skill Subset ideas: SKILL.md structure, progressive disclosure, activation metadata, task/error/user-correction skill decisions, and separated candidate/promoted/rejected/merged registries. Do not introduce Hermes Agents runtime, memory, profiles, personalities, toolsets, plugins, UI, or automation framework.

Message Contract v1

Send messages as single-line records so inbox/history output stays parseable.

AGMSG-TASK v1 fields:

AGMSG-TASK v1 task_id=<id> repo=<absolute-repo-path> task_file=<path>
allowed_files=<paths-or-see-task-file-section> forbidden_actions=<semicolon-list>
expected_result_file=<path> expected_validation_file=<path>
expected_sandbox_file=<path> expected_learning_file=<path>
expected_autoskill_file=<path> done_signal=AGMSG-RESULT max_turns=<n>
note=act-as-worker-<task-or-role>

AGMSG-RESULT v1 fields:

AGMSG-RESULT v1 task_id=<id> status=ready_for_review|blocked
report=<path> validation=<path> sandbox=<path> learning=<path> autoskill=<path>

AGMSG-ACCEPTANCE v1 fields:

AGMSG-ACCEPTANCE v1 task_id=<id> status=accepted|revise reason=<short-reason> next_action=<action>

Liveness messages:

AGMSG-PING v1 task_id=<id> reason=<short-reason>
AGMSG-PONG v1 task_id=<id> status=alive|blocked note=<short-note>

.orchestration Workspace Layout

• tasks/: orchestrator-authored task specs.
• reports/: worker reports and blocked-task reports.
• validation/: command output and validation evidence.
• acceptance/: orchestrator acceptance, revision, or rejection records.
• sandboxes/: OpenSandbox records or documented fallback records.
• autoskill/config/, autoskill/inputs/, autoskill/runs/, autoskill/outputs/: redacted AutoSkill artifacts.
• learning/: task learning triage records.
• learning/rule_candidates/: candidate reusable rules only.
• skills/candidates/, skills/promoted/, skills/rejected/, skills/merged/: separated skill registry states.
• agmsg/: exported or summarized agmsg history when needed for review.

Orchestrator Playbook

1. Join or confirm the agmsg team and identities with the agmsg scripts.
2. Create the .orchestration directories before assigning work.
3. Write a task file that includes objective, scope, allowed files, forbidden actions, expected artifacts, validation commands, and max turns.
4. Start worker panes if needed. With herdr, send the worker prompt text into the pane and submit it with a carriage return; sending text alone may leave it unsubmitted.
5. Configure delivery deliberately. delivery.sh set turn is useful for turn-end inbox checks; changing delivery mode can kill project watcher processes, so do it before starting long-running project watchers.
6. Send AGMSG-TASK v1 with the exact artifact paths and done_signal=AGMSG-RESULT.
7. Track max_turns. Use AGMSG-PING for liveness if a worker stalls.
8. On AGMSG-RESULT, read the task file and every referenced artifact before deciding.
9. Send AGMSG-ACCEPTANCE v1 status=accepted when done, or status=revise with a narrow reason and next_action when more work is required.

Worker Playbook

1. Read the full AGMSG-TASK v1 message.
2. Switch to the repo and read task_file before editing or running validations.
3. Treat allowed_files as the edit boundary. If it says to see the task file, read that section and follow it exactly.
4. Do not perform any forbidden_actions.
5. Write artifacts to the exact expected paths. Do not invent alternate paths.
6. Put command outputs and validation evidence in expected_validation_file.
7. Put sandbox/OpenSandbox status or fallback rationale in expected_sandbox_file.
8. Put reusable learning triage in expected_learning_file; do not promote rules directly unless the task explicitly allows it.
9. Put AutoSkill run status or a not-used record in expected_autoskill_file.
10. If blocked, still write the report and evidence paths that explain the blocker.
11. Reply with the requested done_signal, normally AGMSG-RESULT v1, and include all artifact paths.

Pitfalls

• Do not start work from the agmsg message alone; read task_file first.
• Do not edit outside allowed_files, even for convenient cleanup.
• Do not perform forbidden actions such as dependency changes, gate changes, product changes, promotion decisions, image builds, or LLM calls when listed.
• Do not collapse candidate, promoted, rejected, and merged skill registry states into one directory.
• Do not put secrets, raw logs with credentials, or unredacted AutoSkill inputs in artifacts.
• Do not install Hermes Agents runtime for this protocol.
• Do not assume herdr text injection submits automatically; send Enter/CR.
• Do not treat AGMSG-ACCEPTANCE status=revise as a new task unless it changes the task file or explicitly provides a next action.