Land a PR by monitoring conflicts, resolving them, waiting for checks, and squash-merging when green; use when asked to land, merge, or shepherd a PR to completion.

2026-06-150

lorenz-commit

ryanlyn/lorenz

Create a well-formed git commit from current changes using session history for rationale and summary; use when asked to commit, prepare a commit message, or finalize staged work.

2026-06-150

lorenz-debug

ryanlyn/lorenz

Investigate stuck runs and execution failures by tracing Lorenz and Codex logs with issue/session identifiers; use when runs stall, retry repeatedly, or fail unexpectedly.

2026-06-150

lorenz-pull

ryanlyn/lorenz

Pull latest origin/main into the current local branch and resolve merge conflicts (aka update-branch). Use when Codex needs to sync a feature branch with origin, perform a merge-based update (not rebase), and guide conflict resolution best practices.

2026-06-150

lorenz-push

ryanlyn/lorenz

Push current branch changes to origin and create or update the corresponding pull request; use when asked to push, publish updates, or create pull request.

2026-06-150

name	lorenz-jira
description	Use Lorenz's Jira tracker tools for raw Jira REST API operations such as issue queries, transitions, comments, and JQL searches.

Jira REST API

Use this skill for raw Jira REST API work during Lorenz app-server sessions.

Primary tools

Lorenz exposes Jira operations through its tracker tool layer. The available tools depend on the tracker kind configured for the session:

jira kind — direct REST API calls to Jira Cloud using basic auth (email + API token).
jira-mcp kind — proxied through an external MCP server with configurable tool names.

Default MCP tool names (when using jira-mcp kind):

Operation	Default tool name
Search	`jira_search`
Read issue	`jira_get_issue`
Transition	`jira_transition_issue`
List comments	`jira_get_comments`
Comment	`jira_add_comment`
Update comment	`jira_update_comment`
Create issue	`jira_create_issue`

Jira REST API patterns

All REST calls target /rest/api/3/ on the configured tracker.base_url. Authentication is HTTP Basic with the configured email and API token.

Read an issue by key

GET /rest/api/3/issue/{issueIdOrKey}?fields=summary,description,status,labels,issuelinks,assignee,priority,created,updated

Response shape:

{
  "id": "10001",
  "key": "PROJ-42",
  "fields": {
    "summary": "Issue title",
    "description": { "type": "doc", "version": 1, "content": [...] },
    "status": {
      "name": "In Progress",
      "statusCategory": { "key": "indeterminate" }
    },
    "labels": ["agent", "bug"],
    "assignee": { "accountId": "abc123", "displayName": "User" },
    "priority": { "name": "High" },
    "issuelinks": [...],
    "created": "2026-01-15T10:00:00.000+0000",
    "updated": "2026-06-10T14:30:00.000+0000"
  }
}

Search issues with JQL

Use the enhanced search endpoint (Jira Cloud removed the legacy /rest/api/3/search):

POST /rest/api/3/search/jql
Content-Type: application/json

{
  "jql": "project = PROJ AND status = \"In Progress\" AND assignee = currentUser()",
  "maxResults": 50,
  "fields": ["summary", "description", "status", "labels", "issuelinks", "assignee", "priority", "created", "updated"]
}

Response uses opaque nextPageToken for pagination (no startAt/total):

{
  "issues": [...],
  "nextPageToken": "eyJ..."
}

Pass nextPageToken in subsequent requests to paginate. Stop when nextPageToken is absent or issues is empty.

Transition an issue (change status)

Two-step process:

Fetch available transitions:

GET /rest/api/3/issue/{issueIdOrKey}/transitions

Response:

{
  "transitions": [
    { "id": "31", "name": "In Progress" },
    { "id": "41", "name": "Done" }
  ]
}

Execute the transition by ID:

POST /rest/api/3/issue/{issueIdOrKey}/transitions
Content-Type: application/json

{
  "transition": { "id": "41" }
}

Always fetch transitions first and match by name (case-insensitive) to find the correct transition ID. Never hardcode transition IDs.

Add a comment

Jira Cloud uses Atlassian Document Format (ADF) for comment bodies:

POST /rest/api/3/issue/{issueIdOrKey}/comment
Content-Type: application/json

{
  "body": {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "paragraph",
        "content": [
          { "type": "text", "text": "Comment text here" }
        ]
      }
    ]
  }
}

Multi-line text: split on newlines, each line becomes a separate paragraph. Empty lines become paragraphs with empty content arrays.

List comments

GET /rest/api/3/issue/{issueIdOrKey}/comment?startAt=0&maxResults=100

Response comments use ADF in body. Use comment id values with the update endpoint.

Update a comment

Jira Cloud uses ADF for comment bodies:

PUT /rest/api/3/issue/{issueIdOrKey}/comment/{id}
Content-Type: application/json

{
  "body": {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "paragraph",
        "content": [
          { "type": "text", "text": "Updated comment text" }
        ]
      }
    ]
  }
}

For Jira MCP trackers, configure tracker.mcp.tools.list_comments or tracker.mcp.tools.update_comment when the external server does not expose the default jira_get_comments and jira_update_comment tool names.

Create an issue

POST /rest/api/3/issue
Content-Type: application/json

{
  "fields": {
    "project": { "key": "PROJ" },
    "issuetype": { "name": "Task" },
    "summary": "Issue title",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [{ "type": "text", "text": "Description text" }]
        }
      ]
    },
    "assignee": { "accountId": "abc123" }
  }
}

Get current user

GET /rest/api/3/myself

Returns accountId and displayName for the authenticated user.

Get project statuses

GET /rest/api/3/project/{projectKeyOrId}/statuses

Returns issue types with their available statuses — useful for discovering valid transition targets.

JQL patterns

Common JQL clauses:

project = "PROJ"
project in ("PROJ1", "PROJ2")
status = "In Progress"
status in ("To Do", "In Progress")
assignee = currentUser()
assignee = "accountId"
labels = "agent"
key = "PROJ-42"
key in ("PROJ-1", "PROJ-2", "PROJ-3")
id in (10001, 10002)
updated >= -7d
ORDER BY priority ASC, updated DESC

Combine with AND/OR and parentheses for complex queries.

Atlassian Document Format (ADF)

Jira Cloud API v3 uses ADF for rich text fields (description, comment.body). Minimal document structure:

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "Plain text" }
      ]
    }
  ]
}

Common node types:

paragraph — block of inline text
heading — has attrs: { level: 1..6 }
bulletList / orderedList — contain listItem children
codeBlock — fenced code, has attrs: { language: "..." }
text — inline text, optionally with marks for bold/italic/code/link

When reading descriptions, recursively extract .text fields from the ADF tree and join with appropriate separators (space within paragraphs, newline between blocks).

Usage rules

For status transitions, always fetch available transitions first and match by name — transition IDs are workflow-specific and cannot be assumed.
Use the narrowest JQL that covers your need — avoid ORDER BY on large result sets when you only need a few issues.
Prefer issue keys (e.g. PROJ-42) over numeric IDs when referencing issues.
When creating or commenting, always use ADF format for the body — plain strings are rejected by Jira Cloud API v3.
Do not hardcode status category keys; use the returned statusCategory.key values (new, indeterminate, done) for state type classification.
For the jira-mcp kind, the tool names may differ from defaults — check tracker.mcp.tools configuration for the session's actual tool names.
Do not introduce new raw-token shell helpers for Jira API access.