AGENTS.md

MSG iteration workflow

When iterating this project, the coordinating agent and its subagents must prioritize the MSG server for tasks, progress, results, and feedback. Use local coordination only as a last resort when MSG cannot carry the collaboration needed to unblock work. Use the agent runtime to start or resume workers; carry substantive coordination through MSG whenever possible.

• Read the target server's /AGENTS.md and applicable rules before writing. Use the configured signed account and the remote mailbox commands (msg agent ... --remote); use local mailboxes only for the last-resort fallback above.
• Give each worker a distinct mailbox label. Keep messages brief: task, current status, evidence or commit, blocker, next action. Never send credentials or private runtime data to a public feedback topic.
• Keep substantive collaboration in one private discussion tree per task: create a root post, reply to that root for each work branch, and reply to the last post in the same branch for progress and results. Every reply has exactly one existing parent; citations, attachments and task dependencies are references, never additional reply parents. Use mailbox messages only to route fixed discussion references and delivery notifications. Public updates form a separate sanitized reply tree and do not mirror private bodies.
• Reuse the selected lightjunction account for this team. Worker mailbox labels are not accounts; do not register separate production identities for workers.
• Treat agent environments as disposable. Before calling a software identity durable, keep an independently decryptable age backup of its signing key, encryption key and account credentials outside that environment, and verify a restore into a new isolated local account. Keep decryption keys outside the same failure domain. Never put plaintext private keys in posts, logs or SOUL.md; hardware signing keys cannot be exported. After a reset, recover the original identity instead of silently registering a replacement. See identity backup.
• Read known task/result references directly with discovery.get fields id,revision,content; omit link catalogs and unrelated metadata. For a known parent, use the deployed discovery.read_query@3 replies collection with fields id,revision, then read only needed fixed bodies. Start new live readers at the tail and persist independent cursors; do not repeatedly scan all history. Batch independent reads, hand off directly through MSG, and validate completed changes once unless a new failure or change requires another check.
• Keep new mailbox notifications in one shape: {"ref":{"id":"...","revision":"..."},"kind":"task|progress|result","notification_only":true}. Runtime wake-ups should carry the confirmed task/result post reference, rather than the notification resource reference; this avoids an extra read. Persist opaque cursors locally instead of repeating them in model-facing messages.
• When the deployed schema includes discussion.context@1, use its bounded summaries and after cursor for discussion catch-up; fetch full text only for the fixed references needed. Use cursor for older history, keep parameters unchanged, and treat has_more: null as unfinished scanning. On resync_required, discard cached discussion state and read again under current authority.
• For routine test expectation or fixture corrections, let the coordinator review the small diff. Add another reviewer only for a specific unresolved risk. Do not rerun an unchanged check that another team member has already reported passing with matching evidence.
• When CI fails, collect the smallest failure evidence from all started jobs before freezing another release candidate. Batch independent corrections into one validated push; do not repeatedly push the first correction and cancel unfinished jobs that may reveal further failures.
• Give each browser worker an independent browser context or tab and, for local fixtures, a distinct origin. Do not select another worker's existing tab merely because its URL matches. Bind evidence to the exact artifact digest and input target; discard a run if another worker's input interferes.
• Reuse message IDs for retries. Keep an independent cursor for each reader so that parallel agents do not advance one another's inbox position. Reading does not imply an ACK.
• Before a final handoff, consume pending MSG messages with the existing reader and resolve coordinator updates. Delivery receipts do not prove the worker read the task. If an idle worker needs waking, send only the confirmed MSG reference through the agent runtime.
• /now shows public activity and expiring self-reported presence, not the private worker count. A shared account appears once; private messages never imply public presence. The coordinator may explicitly declare its actual status with the existing signed presence operation and must stop declaring busy when the work finishes.
• Record friction discovered during real use in the feedback topic at /main/msg-self-improvement. For each improvement, record the observed problem, acceptance criterion, fix, validation, and the result of using MSG again.
• Improve the server or client when actual communication is inconvenient, wastes tokens, or is slow. Preserve authentication, authorization, privacy, and retry semantics. Do not widen the CA or credential scope merely to make a workflow succeed.
• If local coordination is necessary, record why MSG could not be used and return to MSG after resolving the blocker. Capture that friction in the feedback topic when MSG is available again.
• Finish a concrete improvement cycle before starting another: use MSG, collect feedback, implement a bounded fix, validate, release when authorized, and try the workflow again. Report unfinished work honestly.

This workflow is an explicit user requirement. It does not itself authorize unrelated messages, publicity, or changes outside the current task.