jira

Files (4)

• SKILL.md
• custom-fields.md · references/
• discover-fields.mjs · scripts/
• jira.mjs · scripts/

SKILL.md (first lines)

# Jira

Interact with Jira Cloud (`https://your-base-url.atlassian.net`) via REST API v3.

## Setup

Run once, then add to your shell profile (`~/.zshrc` or `~/.bashrc`):

```bash
export JIRA_BASE_URL=your-base-url.atlassian.net
export JIRA_EMAIL=you@example.com
export JIRA_API_TOKEN=<token>  # generate at: https://id.atlassian.com/manage-api-tokens
export JIRA_PROJECT=PROJ       # default project key; omit to pass --project on every call
```

**Custom field IDs** — run the discovery script once and export these two variables:

```bash
node ${CLAUDE_SKILL_DIR}/scripts/discover-fields.mjs story        # find User Story field ID
node ${CLAUDE_SKILL_DIR}/scripts/discover-fields.mjs acceptance   # find Acceptance Criteria field ID

export JIRA_FIELD_STORY=customfield_XXXXX
export JIRA_FIELD_AC=customfield_XXXXX
```

See [references/custom-fields.md](references/custom-fields.md) for full details.

Verify with:

```bash
node ${CLAUDE_SKILL_DIR}/scripts/jira.mjs whoami
```

## Read an issue

```bash
node ${CLAUDE_SKILL_DIR}/scripts/jira.mjs get PROJ-123
```

## Create an issue

```bash
node ${CLAUDE_SKILL_DIR}/scripts/jira.mjs create \
  --project PROJ \
  --type Story \
  --summary "User can reset their password" \
  --description "Implement the forgot-password flow." \
  --story "As a user\nI want to reset my password\nSo that I can regain access to my account" \
  --ac "Given I am on the login page\nWhen I click Forgot Password\nThen I receive a reset email within 60 seconds" \
  --assignee me
```

`--project` can be omitted if `JIRA_PROJECT` is set. `--type` defaults to `Story`. Other values: `Bug`, `Task`, `Epic`, `Subtask`.
`--assignee` accepts an email address or `me` for the authenticated user.

Subtasks require `--parent <key>` and use `--type Subtask` (not `Task`, which ignores `parent`):

```bash
node ${CLAUDE_SKILL_DIR}/scripts/jira.mjs create --type Subtask --parent PROJ-42 --summary "Write the migration script"
```

Some projects' permission schemes reject self-assignment on subtasks — if `--assignee` fails on a `Subtask`, omit it and assign separately.

## Update an issue

```bash
# Update fields
node ${CLAUDE_SKILL_DIR}/scripts/jira.mjs update PROJ-123 \
  --summary "Revised summary" \
  --ac "Updated acceptance criteria"

# Transition status
node ${CLAUDE_SKILL_DIR}/scripts/jira.mjs update PROJ-123 --status "In Progress"

# Both at once
node ${CLAUDE_SKILL_DIR}/scripts/jira.mjs update PROJ-123 --status "In Review" --story "Revised story text"
```

## Search with JQL

```bash
node ${CLAUDE_SKILL_DIR}/scripts/jira.mjs search "project = PROJ AND status = 'In Progress'" --max 20
```

Common patterns:

- `assignee = currentUser() AND status != Done`
- `sprint in openSprints() AND project = PROJ`
- `issuetype = Story AND labels = frontend ORDER BY created DESC`
- `updated >= -7d ORDER BY priority DESC`

## Comment on an issue

```bash
node ${CLAUDE_SKILL_DIR}/scripts/jira.mjs comment add PROJ-123 "Deployed to staging, ready for QA."
node ${CLAUDE_SKILL_DIR}/scripts/jira.mjs comment list PROJ-123
```

## Next story, parent epic, blocking links

```bash
node ${CLAUDE_SKILL_DIR}/scripts/jira.mjs next --label ready-for-agent   # first by Rank: open sprint, else backlog; Story, To Do
node ${CLAUDE_SKILL_DIR}/scripts/jira.mjs set-parent PROJ-123 PROJ-1     # make PROJ-1 the parent epic of PROJ-123
node ${CLAUDE_SKILL_DIR}/scripts/jira.mjs link PROJ-10 PROJ-11           # PROJ-10 blocks PROJ-11 ("Blocks" link)
node ${CLAUDE_SKILL_DIR}/scripts/jira.mjs resolve                        # backend/project/site from docs/agents/issue-tracker.md
```

`get` also prints the parent epic's description and, when the issue's or the parent's description links to `docs/blueprints/<key>-<slug>.md` (or the older `docs/epics/`), a labelled `Blueprint:` path for each, to read from the repo. When the repo has `docs/agents/issue-tracker.md`, its project key and site apply (`--project` still wins). The `tracker` skill wraps these commands in a backend-neutral contract.

## Custom fields

Stories have three rich-text fields — `description`, `story` (User Story), and `ac` (Acceptance Criteria).

- `--story` text is split on "As a", "I want", and "So that" clauses — each becomes its own paragraph. Inline or `\n`-separated input both work.
- `--ac` text is converted to a Jira task list; each `\n`-separated line becomes an unchecked task item.

See [references/custom-fields.md](references/custom-fields.md) for field discovery, ADF details, and advanced configuration.

From tforster/agents0, MIT.

More from tforster/agents0