Skip to main content

Common Workflows

Practical patterns for using AgentGate in everyday project management. Examples use MCP tool names — the same operations are available via the CLI.

Starting a Session​

Every session should begin with prime to understand the current project state:

prime()

This returns in-progress issues, pending changes waiting for review, failed changes that need attention, and tips for effective tool use.

For multi-project awareness:

prime()                           # Default project
prime(project_key: "OTHER")       # Another project

Finding Issues​

By status:

issues_list(status: "in_progress")
issues_list(status: "open")
issues_list(status: "done", limit: 5)

By assignee:

issues_list(assignee: "me")
issues_list(assignee: "unassigned")

By label:

issues_list(labels: ["urgent", "backend"])

By parent (children of an Epic):

issues_list(parent: "PROJ-100")

With JQL:

issues_list(jql: "project = PROJ AND text ~ 'marketplace'")
issues_list(jql: "project = PROJ AND priority = High AND status != Done")
issues_list(jql: "project = PROJ AND updated >= -24h ORDER BY updated DESC")

Paginating large result sets:

result = issues_list(limit: 10)
# result includes nextPageToken when hasMore is true
issues_list(next_page_token: "token_from_previous_result")

Reading Issue Details​

Basic details:

issues_show(key: "PROJ-123")

Full context (parent chain, siblings, children, links, recent comments):

issues_context(key: "PROJ-123", children_depth: 2)

Just the children:

issues_children(key: "PROJ-100")
issues_children(key: "PROJ-100", recursive: true)  # Full tree

Creating Issues​

Simple issue:

changes_create(
  type: "create",
  proposed: {
    summary: "Fix login timeout on mobile",
    issueType: "Bug",
    priority: "High",
    description: "Users on iOS report 30s timeout on login..."
  },
  reason: "Reported by 3 users in the last week"
)

Epic with child Stories:

changes_create(
  type: "create",
  proposed: {
    summary: "User Authentication Overhaul",
    issueType: "Epic",
    children: [
      { summary: "Implement OAuth 2.0 login", issueType: "Story" },
      { summary: "Add password reset flow", issueType: "Story" },
      { summary: "Write authentication tests", issueType: "Task" }
    ]
  },
  reason: "Q2 security initiative"
)

Approving the parent creates the Epic and all children with correct parent links.

Issue with links:

changes_create(
  type: "create",
  proposed: {
    summary: "Investigate performance regression",
    issueType: "Task",
    links: [
      { type: "is blocked by", direction: "inward", targetKey: "PROJ-100" },
      { type: "relates to", direction: "outward", targetKey: "PROJ-99" }
    ]
  }
)

Updating Issues​

changes_create(
  type: "update",
  issue_key: "PROJ-123",
  proposed: {
    summary: "Updated title",
    priority: "High",
    labels: ["backend", "urgent"]
  },
  reason: "Reprioritizing based on customer escalation"
)

Transitioning Issues​

issues_transition(
  key: "PROJ-123",
  status: "In Progress",
  reason: "Starting work on this"
)

To see available transitions first:

issues_transitions(key: "PROJ-123")

Adding Comments​

comment(
  key: "PROJ-123",
  body: "Investigated the root cause. The timeout is caused by..."
)

Assigning Issues​

issues_assign(key: "PROJ-123", assignee: "me")
issues_assign(key: "PROJ-123", assignee: null)  # Unassign

Working with Attachments​

Download:

issues_attachments_download(key: "PROJ-123")
issues_attachments_download(key: "PROJ-123", attachment_id: "123")

Upload (max 2MB):

issues_attachments_upload(key: "PROJ-123", file_path: "/path/to/report.pdf")

Managing Pending Changes​

changes_list(status: "pending")          # What's waiting for review
changes_show(id: "chg-abc123")           # View details and diff
changes_update(id: "chg-abc123",         # Modify before review
  proposed: { priority: "Highest" },
  reason: "Escalated by customer"
)
changes_cancel(id: "chg-abc123")         # Cancel if no longer needed

Sprint Management Pattern​

A typical sprint management session:

1. prime()                                              # Get project overview
2. issues_list(status: "in_progress")                   # What's being worked on
3. issues_list(assignee: "unassigned", status: "open")  # What needs assignment
4. issues_assign(key: "PROJ-45", assignee: "me")        # Pick up work
5. issues_transition(key: "PROJ-45", status: "In Progress")
6. comment(key: "PROJ-45", body: "Starting analysis...")
7. # ... do the work ...
8. issues_transition(key: "PROJ-45", status: "Done")

Board Audit Pattern​

Review the full project state and identify issues needing attention:

1. prime()                                                      # Overview
2. issues_list(status: "in_progress")                           # Active work
3. issues_list(jql: "status != Done ORDER BY updated ASC", limit: 10)  # Stale issues
4. issues_list(labels: ["NEEDS_HUMAN"])                         # Blocked on humans
5. changes_list(status: "failed")                               # Failed changes to retry