managing-jira-recipe

Jira Operations

Quick Reference

IMPORTANT: Use inline environment variables with bash -c for commands with pipes (jq, grep, etc.)

Pattern for piped commands:

JIRA_EMAIL="user@example.com" JIRA_API_TOKEN="token" JIRA_BASE_URL="https://impetusde.atlassian.net" bash -c 'curl -s "$JIRA_BASE_URL/rest/api/3/issue/SKL-123/comment" -H "Authorization: Basic $(echo -n "$JIRA_EMAIL:$JIRA_API_TOKEN" | base64 | tr -d '\''\n'\'')" -H "Content-Type: application/json" | jq ".total"'

Pattern for simple commands (no pipes):

# Load from .env first
source <claudes-kitchen-dir>/.env

# Then use directly
curl -s "$JIRA_BASE_URL/rest/api/3/issue/SKL-123" -H "Authorization: Basic $(echo -n "$JIRA_EMAIL:$JIRA_API_TOKEN" | base64 | tr -d '\n')" -H "Content-Type: application/json"

Common operations:

# Get comments with jq
JIRA_EMAIL="user@example.com" JIRA_API_TOKEN="token" JIRA_BASE_URL="https://impetusde.atlassian.net" bash -c 'curl -s "$JIRA_BASE_URL/rest/api/3/issue/SKL-123/comment" -H "Authorization: Basic $(echo -n "$JIRA_EMAIL:$JIRA_API_TOKEN" | base64 | tr -d '\''\n'\'')" | jq ".total"'

# Search issues via JQL (POST /rest/api/3/search/jql — /search removed Apr 2026)
JIRA_EMAIL="user@example.com" JIRA_API_TOKEN="token" JIRA_BASE_URL="https://impetusde.atlassian.net" bash -c 'curl -s -X POST "$JIRA_BASE_URL/rest/api/3/search/jql" -H "Authorization: Basic $(echo -n "$JIRA_EMAIL:$JIRA_API_TOKEN" | base64 | tr -d '\''\n'\'')" -H "Content-Type: application/json" -d '"'"'{"jql": "project = SKL AND statusCategory != Done ORDER BY duedate ASC", "fields": ["summary","status","assignee","duedate","priority"], "maxResults": 50}'"'"' | jq '"'"'.issues[] | {key: .key, summary: .fields.summary, status: .fields.status.name, due: .fields.duedate, assignee: (.fields.assignee.displayName // "Unassigned")}'"'"''

# Create issue (no pipe - can use source)
source <claudes-kitchen-dir>/.env && curl -X POST "$JIRA_BASE_URL/rest/api/3/issue" -H "Authorization: Basic $(echo -n "$JIRA_EMAIL:$JIRA_API_TOKEN" | base64 | tr -d '\n')" -H "Content-Type: application/json" -d '{"fields": {"project": {"key": "SKL"}, "issuetype": {"name": "Task"}, "summary": "Title"}}'

# Open browser
open https://impetusde.atlassian.net/browse/SKL-123

When to Use

Create tickets | update issues | change status | search JQL | link epics/subtasks

Environment

Central .env location:

<claudes-kitchen-dir>/.env

Setup:

cd <claudes-kitchen-dir>
cp .env.example .env

Required vars:

JIRA_EMAIL=your.email@company.com
JIRA_API_TOKEN=your-token
JIRA_BASE_URL=https://impetusde.atlassian.net

Common typos:

• JIRA_BASE_UR= → WRONG (missing L)
• JIRA_BASE_URL= → CORRECT

Usage patterns:

# For commands with pipes (jq, grep, etc.) - use inline env vars with bash -c
JIRA_EMAIL="..." JIRA_API_TOKEN="..." JIRA_BASE_URL="..." bash -c 'curl ... | jq ...'

# For simple commands (no pipes) - source .env first
source <claudes-kitchen-dir>/.env && curl ...

export VAR="x" && ... | jq → zsh scoping issues → piped subprocesses don't inherit vars → silent failures

Portable base64 encoding:

All commands use base64 | tr -d '\n' for cross-platform compatibility:

• Linux base64 wraps output at 76 chars (breaks HTTP headers)
• macOS/BSD base64 doesn't support -w flag
• Solution: tr -d '\n' removes newlines universally
• HTTP Basic Auth headers cannot contain newlines

Custom Fields (Andercore)

customfield_10001 → Team (requires UUID)
customfield_10014 → Epic Link (epic key)
customfield_10061 → Story Points (numeric)

See custom-fields.md for UUID lookup and usage.

Story Points

User provided → use value
Not provided → estimate:
  1 → trivial
  2 → simple
  3 → standard
  5 → complex
  8 → very complex
  13 → epic-level

By task count:
  1-3 tasks → 3 points
  4-6 tasks → 5 points
  7-10 tasks → 8 points
  11+ tasks → 13 points

References

setup.md:

Environment setup → .env configuration
API token → Atlassian credentials
Troubleshooting → Common issues

api-reference.md:

Endpoints → GET/POST/PUT
Format → Atlassian Document
Errors → 400/401/403/404/429
Auth → Basic + base64

JQL Patterns

assignee = currentUser() AND updated >= -7d
labels IN (frontend, urgent) AND status != Done
created >= startOfMonth() AND type = Bug
issueFunction in epicsOf("key = CPL-123")
parent = CPL-424

Rules

Status change → get transitions → transition (mandatory)
Team assign → lookup UUID dynamically (mandatory)
Field IDs → never assume (instance-specific)

Decision Tree

REST API operations:

Create → curl -X POST $JIRA_BASE_URL/rest/api/3/issue
Update → curl -X PUT $JIRA_BASE_URL/rest/api/3/issue/{key}
Status → curl GET transitions → curl POST transitions
Search → curl -X POST $JIRA_BASE_URL/rest/api/3/search/jql
Details → curl GET $JIRA_BASE_URL/rest/api/3/issue/{key}

Custom fields:
├─ Epic link → customfield_10014
├─ Subtask → parent field + Sub-task type
└─ Unknown field → GET /field

Validation Workflow (Execute After Jira Operations)

MANDATORY: Run after ticket creation/update/status change.

Phase	Action
1. Execute	Perform Jira operation (create/update/status/search)
2. Validate	Review conversation context for workflow compliance
3. Report	✓ Pass → Done | ✗ Fail → List violations with evidence
4. Fix	Violations found → Correct → Re-run operation
5. Store Metrics	After ALL validation passes, call mcp__agent-orchestrator__store-skill-metrics

Validation method:

Review conversation tool calls (NOT re-run commands)
→ Verify workflow steps occurred
→ Check temporal order (get transitions BEFORE status change)
→ Cite tool call evidence in report

Validation checks:

Operation	Verification Method
Create	Check REST API call with required fields in conversation
Update	Check issue key validated before update
Status	GET transitions BEFORE POST transitions
Search	Check JQL syntax and results in conversation

Output format (with context evidence):

VALIDATION REPORT:
✓ Ticket created: CPL-1234 [Evidence] POST /issue succeeded
✓ Required fields: summary, issue_type, project_key
✓ Team UUID: Resolved dynamically [Evidence] customfield_10001 lookup
✓ Status change: [Evidence] GET transitions called BEFORE POST transitions

ALL CHECKS PASS ✓

Example with violation:

VALIDATION REPORT:
✗ FAIL: Status change without getting transitions
✗ Evidence: POST transitions called, no GET transitions in conversation
✗ FAIL: Custom field ID assumed

VIOLATIONS (2):
1. Missing GET transitions call before status change
   Evidence: No GET /transitions in conversation
2. customfield_10001 not validated
   Evidence: No field lookup before use

ACTION: Fix violations and re-validate

Re-validation required after fixes. Repeat until ALL checks pass.