jira-manager

Files (6)

• SKILL.md
• jira-links-and-attachments.md · references/
• jira-sprints.md · references/
• jira-workflow.md · references/
• variables.example.jsonc · references/
• .gitignore · sensitive/

SKILL.md (first lines)

# Jira Issue Tracker

You are a Jira administrator using the `jira` CLI. Work in the project and team specified by `sensitive/variables.json`, not the examples below.

## When to use this skill

Use this skill when the user needs to:
- Create or update Jira issues (bugs, stories, tasks, epics)
- Search for tickets using JQL queries
- Transition issues between workflow states
- Add comments or link issues
- Manage the configured team's backlog

**Examples:**
- "I found a null pointer exception in the payment service. Can you file a bug?"
- "Show me all high priority tickets assigned to me."
- "Create an epic for the new authentication feature with stories for login, logout, and password reset."
- "Move ISSUE-KEY to the requested status."

## Project Context

**Before any Jira operation, read `sensitive/variables.json`.** It is the local, unshared source of project key, Jira base URL, team name, board ID, issue types, priorities, recent epics, description attribution, and custom-field names/IDs. Creating or updating tickets requires the correct field IDs for REST and the configured field names for CLI `--custom` arguments; neither IDs nor field names are portable between Jira instances. Do not infer missing values from the examples in this skill or from another user's configuration. If the file is missing or invalid, stop before changing Jira and ask for a valid copy based on `references/variables.example.jsonc`.

The `jira` CLI reads its own project, board, and custom-field mapping from `~/.config/.jira/.config.yml`. Check that it matches the personal variables before acting; for another project, use `--project` and a matching CLI configuration. The CLI resolves configured custom-field names to IDs for `--custom`; raw Jira responses and REST requests use `field_id`. The JQL field name comes from the same field's `name`. Resolve the CLI aliases for the configured team, acceptance-criteria, and Story Points fields before using the examples below.

`story_points_field` is separate from `custom_fields`: use its `field_id` for reading/verifying raw JSON and REST requests, and its configured `name` for the CLI custom-field alias. The **estimate** is not a configuration default: select it independently from the full scope of each Task, Story, or Bug with the rubric below. Do not change an existing estimate during an unrelated update.

- **Creator**: Always the authenticated `$(jira me)` account. Jira sets this server-side; the CLI has no `--creator` flag.
- **Default reporter**: `$(jira me)` unless the user explicitly requests a different reporter
- **Default assignee**: `$(jira me)` unless the user explicitly requests a different assignee

## Quick Reference

Commands below are templates. Read `sensitive/variables.json`, then resolve `TEAM_FIELD_NAME`, `TEAM_FIELD_ALIAS`, `ACCEPTANCE_CRITERIA_ALIAS`, and `STORY_POINTS_ALIAS` against its field entries and the matching CLI configuration. Choose `STORY_ISSUE_TYPE`, `SUBTASK_ISSUE_TYPE`, and `BUG_ISSUE_TYPE` from `issue_types`; use actual issue keys for `ISSUE_KEY`, `PARENT_KEY`, and `EPIC_KEY`. Never send an unset placeholder to Jira. Select `$STORY_POINTS` independently for each issue with the rubric below. Resolve status and link-type names from Jira before using `STATUS_NAME`, `OPEN_STATUSES`, or any `*_LINK_TYPE` variable; link types and directions are described in [the links reference](references/jira-links-and-attachments.md).

```sh
JIRA_VARIABLES="$HOME/.agents/skills/jira-manager/sensitive/variables.json"
TEAM_NAME=$(jq -r '.team_name' "$JIRA_VARIABLES")
PRIORITY_STANDARD=$(jq -r '.priorities.standard' "$JIRA_VARIABLES")
PRIORITY_HIGH=$(jq -r '.priorities.high' "$JIRA_VARIABLES")
# Resolve TEAM_FIELD_NAME and the three field aliases from the configured custom fields.
TEAM_JQL=$(jq -nr --arg field "$TEAM_FIELD_NAME" --arg team "$TEAM_NAME" '"\($field | @json) = \($team | @json)"')
# Set STORY_POINTS for the particular issue, and ISSUE_KEY / EPIC_KEY from Jira.
# Create issue; capture the returned key, verify Story Points, then apply the sprint policy
jira issue create --type "$STORY_ISSUE_TYPE" --summary "..." --priority "$PRIORITY_STANDARD" --reporter "$(jira me)" --assignee "$(jira me)" --custom "${TEAM_FIELD_ALIAS}=${TEAM_NAME}" --custom "${STORY_POINTS_ALIAS}=${STORY_POINTS}" --custom "${ACCEPTANCE_CRITERIA_ALIAS}=- [ ] Work is complete" --no-input --raw

# Create epic
jira epic create --name "..." --summary "..." --priority "$PRIORITY_HIGH" --reporter "$(jira me)" --assignee "$(jira me)" --custom "${TEAM_FIELD_ALIAS}=${TEAM_NAME}" --no-input

# Edit issue without changing its estimate
jira issue edit "$ISSUE_KEY" --summary "New summary" --body "New description" --no-input

# Re-estimate only on request or after a material scope change
jira issue edit "$ISSUE_KEY" --custom "${STORY_POINTS_ALIAS}=${STORY_POINTS}" --no-input

# Before transitions, read references/jira-workflow.md

# Comment
jira issue comment add "$ISSUE_KEY" "Comment text"

# Search
jira issue list --jql "$TEAM_JQL AND assignee = currentUser() AND status = \"$STATUS_NAME\"" --plain

# View
jira issue view "$ISSUE_KEY" --plain
```

## Required Fields

**ALL issues must include:**
- `--type` (select the configured issue type from `issue_types`)
- `--summary`
- `--priority` (choose the configured value under `priorities`)
- `--custom "${TEAM_FIELD_ALIAS}=${TEAM_NAME}"` (resolve the team field via `custom_fields`)
- `--reporter "$(jira me)"` unless the user explicitly requests a different reporter
- `--assignee "$(jira me)"` unless the user explicitly requests a different assignee
- `--no-input` (required for non-interactive execution)

The creator is not a settable CLI field. Jira automatically records the authenticated `$(jira me)` account as creator. Do not accept or invent a different creator.

**Tasks/Stories/Bugs must include:**
- `--custom "${ACCEPTANCE_CRITERIA_ALIAS}=${CRITERIA}"` (resolve the configured acceptance-criteria field)
- `--custom "${STORY_POINTS_ALIAS}=${STORY_POINTS}"` using the separate `story_points_field` and the Story Points rubric with a minimum floor of `0.5`
- `--parent "$EPIC_KEY"` (if linking to an epic)

Estimate from the full ask before creating the issue. Do not use a fixed default or copy one estimate across a batch. If the user gives a valid estimate, use it. If they give a value outside the allowed sequence, propose the nearest rubric value and get explicit approval before proceeding. Never send the invalid value.

By this team's planning policy, Epics do not receive Story Points even if Jira exposes the field. Sub-tasks receive Story Points only when Jira exposes the field for that issue type and the user explicitly requests a sub-task estimate; otherwise estimate the parent Task, Story, or Bug.

**Sub-task acceptance criteria fallback:**
- Try setting the configured Acceptance Criteria field when it is available.
- If Jira rejects it as a field that cannot be set on a Sub-task, retry without that custom field and include an `## Acceptance criteria` section in the description body. Do not retry creation blindly if a key was returned.

**Searching Issues:**
- Filter by the configured team field `name` and `team_name` in JQL to avoid other teams' tickets/issues; do not use the CLI alias as a JQL field name. Build `TEAM_JQL` as the quoted field name, ` = `, and the quoted team name, escaping embedded quotes and backslashes in both values.

## Shell Escaping for Bodies

Use `$'...'` syntax for bodies with newlines and special characters. Set `CRITERIA` separately when passing multiline acceptance criteria to `--custom`:

```sh
CRITERIA=$'- [ ] Criterion 1\n- [ ] Criterion 2'
# Multi-line body with markdown
jira issue create \
  --type "$STORY_ISSUE_TYPE" \
  --summary "Example story" \
  --priority "$PRIORITY_STANDARD" \
  --body $'## Summary\nBrief description\n\n## Technical Context\n- Component A\n- Component B' \
  --custom "${TEAM_FIELD_ALIAS}=${TEAM_NAME}" \
  --custom "${STORY_POINTS_ALIAS}=${STORY_POINTS}" \
  --reporter "$(jira me)" \
  --assignee "$(jira me)" \
  --custom "${ACCEPTANCE_CRITERIA_ALIAS}=${CRITERIA}" \
  --no-input \
  --raw
```

For bodies with backticks or complex markdown, escape them: `` \` ``

From ahstn/dotfiles, MIT.

More from ahstn/dotfiles