amq-spec
Parallel-research-then-converge design workflow between two agents. Use this skill when the user wants two agents to independently think through a design problem before aligning on a solution — "spec X with codex", "design X together", "both agents think through X", "brainstorm a
Install
npx skills add https://github.com/avivsinai/agent-message-queue/tree/main/skills/amq-spec
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install avivsinai-agent-message-queue@llmmart
git clone https://github.com/avivsinai/agent-message-queue.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole avivsinai/agent-message-queue collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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-maillayout); 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-bodyon its doorbell. Do not startamq watch,amq monitor, or a polling loop. Checkamq wake check --me <handle> --jsonwhen the capability is unknown. A boundedwatchis 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.
Files (agent-message-queue)
-
references
-
spec-workflow.md 5.8 KB
Loading…
-
-
SKILL.md 4.2 KB
--- name: amq-spec version: 0.145.0 # x-release-please-version description: Use two agents to research a design independently and converge on one specification through AMQ. Trigger for collaborative design or messages labeled workflow:spec; use amq-cli for ordinary coordination. argument-hint: "<description of what to design> [with <partner>]" metadata: short-description: Multi-agent collaborative spec workflow compatibility: claude-code, codex-cli --- # 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.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.