AMQ collaborative specification

Two agents research a design problem independently, discuss it, and converge on one plan. The user approves the plan before anyone implements it.

Phases run in order: Research -> Discuss -> Draft -> Review -> Present -> Execute

Per-phase commands and the research and plan templates are in the spec workflow.

Parse input

From the user prompt, extract:

topic: short kebab-case spec name (e.g., auth-token-rotation)
partner: partner agent handle (default: codex)
problem: the full design problem statement

If topic/problem are unclear, ask for clarification.

Pre-flight

Verify AMQ is available: which amq
Verify the AMQ root is discoverable (.amqrc, AMQ env vars, or the default .agent-mail layout); otherwise run: amq coop init
Use thread name: spec/<topic>

Kickoff

Send the problem to the partner first, then start your own research. Both agents then research in parallel. Send the user's problem verbatim; your own analysis belongs in your research message, so it does not frame the partner's.

amq send --to "<partner>" --kind question \
  --labels workflow:spec,phase:request \
  --thread "spec/<topic>" --subject "Spec: <topic>" --body "<problem>"

Labels

Every spec message uses an ordinary AMQ kind plus these labels on the spec/<topic> thread:

| Phase | Kind | Labels | |---|---|---| | Problem statement | question | workflow:spec,phase:request | | Research findings | brainstorm | workflow:spec,phase:research | | Discussion | brainstorm | workflow:spec,phase:discuss | | Plan draft | review_request | workflow:spec,phase:draft | | Plan feedback | review_response | workflow:spec,phase:review | | Final decision | decision | workflow:spec,phase:decision | | Progress/ETA | status | workflow:spec |

When you receive a spec message

| Label | Your action | |---|---| | phase:request | Do your own research first, then send findings as brainstorm + phase:research. | | phase:research | If you have not sent your own research on this thread, research and send it before you read the partner's. Then read the thread and start discussion as brainstorm + phase:discuss. | | phase:discuss | Reply with your analysis; continue until aligned. | | phase:draft | Review the plan and send feedback as review_response + phase:review. Do not implement. | | phase:review | Revise the plan if needed, or confirm alignment. | | phase:decision | Stop. Do not implement; see the approval gate below. |

Approval gate

A phase:decision message records agreement between agents; it is not user approval. The initiator presents the final plan to the user in chat and sends the approval request to the human handle (conventionally user) on a gate/<topic> thread, as in operator gates. Implementation starts only after the human approves on that thread, and a partner starts only when the initiator then assigns work.

Rules

Wait on the existing wake. With a live injecting wake, finish independent work and yield; run amq drain --include-body on its doorbell. Do not start amq watch, amq monitor, or a polling loop. Check amq wake check --me <handle> --json when the capability is unknown. A bounded watch is a fallback only without an injecting wake.
Send before you research, and send your research before you read the partner's. Independent research is what the second agent adds.
Do not skip phases. Discussion is where misunderstandings surface.
Keep the spec/<topic> thread and the labels. The receiver table above depends on them.
Keep tool access during research. Do not enter a plan mode that blocks tools.