Amq Spec

/amq-spec — Collaborative Specification Workflow

This skill defines a structured two-agent specification flow.

Use canonical phases in order: Research -> Discuss -> Draft -> Review -> Present -> Execute

Detailed step-by-step protocol lives in references/spec-workflow.md. This file is the concise operational entrypoint.

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>

First Action: Send problem to partner IMMEDIATELY

The entire point of the spec workflow is parallel research — both agents exploring the problem independently, then comparing notes. Every second you spend researching before sending is a second your partner sits idle waiting for the problem statement. That's why the send comes first, even though your instinct might be to "research first to give better context."

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

Send the user's problem description verbatim — your own analysis goes in the research phase, not the kickoff. If you pre-analyze, you bias the partner's independent research, which defeats the purpose of having two perspectives.

Label Convention

Labels are how both agents and the receiver-side protocol table know which phase the conversation is in. Use existing AMQ kinds plus labels to express spec workflow semantics:

Quick Command Skeleton

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

# Submit independent research
amq send --to <partner> --kind brainstorm \
  --labels workflow:spec,phase:research \
  --thread spec/<topic> --subject "Research: <topic>" --body "<findings>"

# Discuss and align
amq send --to <partner> --kind brainstorm \
  --labels workflow:spec,phase:discuss \
  --thread spec/<topic> --subject "Discussion: <topic>" --body "<analysis>"

# Draft plan
amq send --to <partner> --kind review_request \
  --labels workflow:spec,phase:draft \
  --thread spec/<topic> --subject "Plan: <topic>" --body "<plan>"

# Review plan
amq send --to <partner> --kind review_response \
  --labels workflow:spec,phase:review \
  --thread spec/<topic> --subject "Review: <topic>" --body "<feedback>"

# Optional final decision message
amq send --to <partner> --kind decision \
  --labels workflow:spec,phase:decision \
  --thread spec/<topic> --subject "Final: <topic>" --body "<final plan>"

When You RECEIVE a Spec Message

If you receive a message labeled workflow:spec, your action depends on the phase:

Why the partner doesn't implement: The spec workflow is a design process. The initiator owns the relationship with the user and presents the final plan. If the partner implements without approval, the user loses control over what gets built. The agent-to-agent phase:decision message is alignment, not authorization: human approval is a structural gate to the initialized human handle, and partner agents must not implement from a spec decision alone. Implementation starts only after the initiator explicitly tells you the human approved and assigns work.

Protocol Discipline

These rules exist because violations silently break the workflow's value proposition:

• Send before researching — parallel research is the whole point. Pre-researching wastes your partner's time and biases the outcome toward your initial framing.
• Submit your own research before reading partner's — reading first contaminates your independent perspective. Two agents who read the same code and reach the same conclusion is less valuable than two agents who explore independently and then compare notes.
• Don't skip phases — each phase builds on the previous. Collapsing directly to a finished spec skips the discussion where misunderstandings surface.
• Use `spec/<topic>` threads and the label convention — this is how both agents (and the tooling) know which phase the conversation is in. Without consistent labels, the receiver-side protocol table above breaks.
• Don't enter plan mode during research if it blocks tool usage — you need tools to explore the codebase.
• Present the final plan to the user before executing, and raise a structural gate. The initiator owns the user relationship. After the decision phase, present the plan in chat AND raise a structural human gate using the initialized human handle (conventionally user) on a stable gate/<topic> thread, then wait for explicit approval on that thread. The agent-to-agent phase:decision message is alignment only; partner agents must not implement from it. See the Operator Gates section in /amq-cli for canonical mechanics, seeding, and guardrails.

Reference

For full protocol details, templates, and phase gates, see:

• references/spec-workflow.md

Spec Workflow

Collaborative specification workflow for multi-agent design tasks. The word "spec" is intentionally used to avoid collision with Claude Code plan mode.

Core principle: each agent researches independently first, then both agents discuss and finalize a plan that is presented to the user for approval before implementation.

This is a skill-managed protocol that uses standard AMQ primitives (amq send, amq drain, amq thread) with generic kinds + labels.

DO NOT SKIP PHASES

You MUST follow every phase in order.

What you MUST NOT do:

• Research alone and send a finished spec to partner
• Use invalid kinds — only use generic kinds (question, brainstorm, review_request, etc.) with workflow:spec labels
• Skip the discussion phase
• Send a draft before both agents exchanged research
• Implement before user approval

Phase Order (Canonical)

1. RESEARCH (parallel) -> 2. DISCUSS (ping-pong) -> 3. DRAFT (main agent drafts) -> 4. REVIEW (partner) -> 5. PRESENT (to user) -> 6. EXECUTE

Label Convention (Required)

CRITICAL RULES

Research Independence (Phase 1)

• NEVER read partner research before sending your own.
• Use normal mode with full tool access for research.
• Submit your own findings first, then read partner findings.

Discussion Is Required (Phase 2)

• Discuss architecture decisions after exchanging findings.
• Expect multiple rounds, not a single message.
• Align on approach, risks, and scope before drafting.

User Approval Gate (Phase 5)

• Final plan must be presented to the user in chat.
• ALSO raise a structural gate: send the approval request to the initialized human handle (conventionally user) on a stable gate/<topic> thread. See the Operator Gates section in /amq-cli for canonical mechanics, seeding, and guardrails. An agent-to-agent phase:decision message is NOT the approval.
• Wait for explicit user approval (the human's reply on the gate thread) before execution. Partner agents do not implement from a spec decision alone.

Thread Convention

All spec messages use thread spec/<topic> (example: spec/auth-redesign).

Agent Protocol (Step by Step)

Phase 1: Research (parallel)

Initiating agent (starts the spec):

# 1) Send problem statement request (no findings yet)
amq send --to <partner> --kind question \
  --labels workflow:spec,phase:request \
  --thread spec/<topic> --subject "Spec: <topic>" \
  --body "Problem: <what needs to be designed>"

# 2) Do your own independent research immediately
#    - Explore codebase/files/patterns/constraints
#    - Check external docs if relevant

# 3) Submit your findings
amq send --to <partner> --kind brainstorm \
  --labels workflow:spec,phase:research \
  --thread spec/<topic> --subject "Research: <topic>" \
  --body "<your findings using template below>"

# 4) Wait for partner findings
amq watch --timeout 120s

Receiving agent (got the kickoff request):

# 1) Do your own independent research FIRST
#    - Read the kickoff problem statement
#    - Do not read partner research from the thread yet

# 2) Submit your findings
amq send --to <partner> --kind brainstorm \
  --labels workflow:spec,phase:research \
  --thread spec/<topic> --subject "Research: <topic>" \
  --body "<your findings>"

# 3) Then read full thread
amq thread --id spec/<topic> --include-body

Phase 2: Discuss (ping-pong)

# Read both research submissions
amq thread --id spec/<topic> --include-body

# Discuss differences, trade-offs, and decisions
amq send --to <partner> --kind brainstorm \
  --labels workflow:spec,phase:discuss \
  --thread spec/<topic> --subject "Discussion: <topic>" \
  --body "<analysis + open questions>"

# Continue rounds until aligned
amq watch --timeout 120s
amq drain --include-body

Phase 3: Draft (main agent)

amq send --to <partner> --kind review_request \
  --labels workflow:spec,phase:draft \
  --thread spec/<topic> --subject "Plan: <topic>" \
  --body "<plan using template below>"

Phase 4: Review (partner)

amq send --to <partner> --kind review_response \
  --labels workflow:spec,phase:review \
  --thread spec/<topic> --subject "Review: <topic>" \
  --body "<review feedback>"

# If needed: main agent revises and re-sends draft

Phase 5: Present to User

Main agent must: 1. Synthesize final plan from discussion + review 2. Present it directly to user in chat 3. Raise a structural gate: address the approval request to the initialized human handle (conventionally user) on a stable gate/<topic> thread:

   # See the Operator Gates section in /amq-cli for human-handle seeding and guardrails.
   amq send --to user --thread gate/<topic> --kind question \
     --subject "APPROVAL: <decision>" \
     --body "<final plan summary; what you need the human to approve>"

4. Wait for explicit approval (the human's reply on the gate/<topic> thread) 5. Not implement before approval; partner agents must NOT implement from the agent-to-agent phase:decision message alone

The phase:decision message below is an optional partner alignment marker, not the user approval. See /amq-cli's Operator Gates section for the canonical mechanics and guardrails.

Optional partner notification after alignment:

amq send --to <partner> --kind decision \
  --labels workflow:spec,phase:decision \
  --thread spec/<topic> --subject "Final: <topic>" \
  --body "<final agreed plan>"

Phase 6: Execute

Only after user approval. Follow user direction on scope and rollout.

Tracking Progress

Use the thread to inspect current phase:

amq thread --id spec/<topic> --include-body

Phase indicators:

• labels=workflow:spec,phase:request -> kickoff/problem statement
• labels=workflow:spec,phase:research -> research submissions
• labels=workflow:spec,phase:discuss -> discussion rounds
• labels=workflow:spec,phase:draft -> plan draft
• labels=workflow:spec,phase:review -> plan review feedback
• labels=workflow:spec,phase:decision -> final agreed plan

Research Summary Template

## Problem Understanding
<your interpretation in your own words>

## Codebase Findings
- <relevant files/patterns/constraints>
- <existing implementations>
- <integration points>

## Proposed Approach
<high-level direction>

## Open Questions
- <questions for discuss phase>

## Risks
- <key risks>

Spec Draft Template (Plan)

## Problem Statement
<clear problem definition>

## Proposed Solution
<concrete solution>

## Architecture
<design/components/interactions>

## File Changes
- `path/to/file.ext` — what changes and why

## Decisions Made
- <decision>: <chosen option> because <rationale>

## Trade-offs Considered
- <option A vs B> — why chosen

## Edge Cases
- <case> — handling

## Testing Strategy
- <verification approach>

## Risks
- <risk> — mitigation