amq-spec

# 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](references/spec-workflow.md). ## 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 1. Verify AMQ is available: `which amq` 2. Verify the AMQ root is discoverable (`.amqrc`, AMQ env vars, or the default `.agent-mail` layout); otherwise run: `amq coop init` 3. 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. ```bash 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](https://github.com/avivsinai/agent-message-queue/blob/main/skills/amq-cli/references/operations.md#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.