Claude Skill

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

LLM Mart · 0 points · 15 views 0 listing impressions 0 install-command copies
Download avivsinai-agent-message-queue-skills_amq-spec-67858b7.zip · 4 KB

Install

skills CLI npx skills add https://github.com/avivsinai/agent-message-queue/tree/main/skills/amq-spec
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install avivsinai-agent-message-queue@llmmart
Git 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

  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.

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.
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.

No comments yet.

Reviews (0)

No reviews yet.