Add jira-dmtools Cursor Agent skill

.cursor/skills/jira-dmtools/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: jira-dmtools
+description: Perform JIRA operations via dmtools CLI. Flow: (1) verify JIRA connection via verify script; (2) run script without --verify to create/refresh .dmtools/jira.cfg if missing; (3) select command from Command index by task, read commands/<folder>/SKILL.md, run dmtools. JIRA config in dmtools.env (JIRA_BASE_PATH, JIRA_EMAIL, JIRA_API_TOKEN).
+---
+
+# JIRA operations with dmtools CLI
+
+## Agent flow (follow in order)
+
+1. **Verify JIRA connection**  
+   Run from repo root: `python .cursor/skills/jira-dmtools/scripts/verify_jira_connection.py --verify`  
+   This checks that `.dmtools/jira.cfg` exists and is valid. Connection is driven by **dmtools.env** (or env vars): `JIRA_BASE_PATH`, `JIRA_EMAIL`, `JIRA_API_TOKEN`.
+
+2. **Create or refresh config if missing/invalid**  
+   If step 1 fails (no jira.cfg or invalid), run: `python .cursor/skills/jira-dmtools/scripts/verify_jira_connection.py`  
+   This uses dmtools.env, calls JIRA, and writes `.dmtools/jira.cfg` on success. Optionally add `--project PROJ` to cache issue types, statuses, components.
+
+3. **Select and run the command**  
+   Once jira.cfg is present, match the user's task to the **"When to use"** column in the Command index table below. Open the indicated `commands/<folder>/SKILL.md`, then run the corresponding `dmtools` command (positional args or `--data '<JSON>'`).
+
+**On 401/403/timeout** during a dmtools call: re-run step 2 to refresh config, then retry the command.
+
+**Identifying failures quickly:** For workflow (move/transition) commands, 404 with a mangled URL (e.g. path containing `statusName/:/Partial` with the status name cut off) usually means the shell split the `--data` JSON—use single-quoted JSON. For other commands, see the "Avoiding malformed API URLs" / "Identifying issues faster" section in the relevant `commands/<folder>/SKILL.md`.
+
+## How to invoke
+
+Run `dmtools <tool_name>` in the terminal. Use positional args for simple calls or `--data '<JSON>'` for complex ones. Output is JSON on stdout.
+
+**List all JIRA tools:** `dmtools list | jq '.tools[] | select(.name | startswith("jira_"))'`
+
+**Subskills:** For each group below, read `commands/<folder>/SKILL.md` when the task matches the "When to use" description; that file has the exact command and parameters.
+
+## Command index
+
+| Group | When to use | Tools |
+|-------|-------------|-------|
+| **Search** | Search or list tickets by JQL, project, status, or with paging. | `commands/search` → `jira_search_by_jql`, `jira_search_by_page`, `jira_search_with_pagination` |
+| **Read** | Get one ticket, its subtasks, comments, or available transitions. | `commands/tickets-read` → `jira_get_ticket`, `jira_get_subtasks`, `jira_get_comments`, `jira_get_transitions` |
+| **Create** | Create a ticket (basic, with custom fields, or as subtask under parent). | `commands/ticket-create` → `jira_create_ticket_basic`, `jira_create_ticket_with_json`, `jira_create_ticket_with_parent` |
+| **Update** | Change fields, description, parent, or clear a field on a ticket. | `commands/ticket-update` → `jira_update_ticket`, `jira_update_field`, `jira_update_description`, `jira_update_all_fields_with_name`, `jira_update_ticket_parent`, `jira_clear_field` |
+| **Delete** | Delete a ticket (irreversible). | `commands/ticket-delete` → `jira_delete_ticket` |
+| **Workflow** | Move ticket to a status, set resolution, or assign to a user. | `commands/workflow` → `jira_move_to_status`, `jira_move_to_status_with_resolution`, `jira_assign_ticket_to` |
+| **Profile** | Resolve account ID by email, get current user or another user's profile. | `commands/profile` → `jira_get_account_by_email`, `jira_get_my_profile`, `jira_get_user_profile` |
+| **Comments** | Add a comment or add only if not already present; read comments is under Read. | `commands/comments` → `jira_post_comment`, `jira_post_comment_if_not_exists` |
+| **Fix versions** | List, set, add, or remove fix version(s) on a ticket or project. | `commands/fix-versions` → `jira_get_fix_versions`, `jira_set_fix_version`, `jira_add_fix_version`, `jira_remove_fix_version` |
+| **Links & labels** | List link types, link two issues, add label, or set priority. | `commands/links-labels-priority` → `jira_get_issue_link_types`, `jira_link_issues`, `jira_add_label`, `jira_set_priority` |
+| **Fields data** | Get field definitions or custom field ID(s) by display name for a project. | `commands/fieldsdata` → `jira_get_fields`, `jira_get_field_custom_code`, `jira_get_all_fields_with_name` |
+| **Metadata** | Get issue types, statuses, or components for a project. | `commands/metadata` → `jira_get_issue_types`, `jira_get_project_statuses`, `jira_get_components` |
+| **Attachments** | Attach a file to a ticket or download an attachment by URL. | `commands/attachments` → `jira_attach_file_to_ticket`, `jira_download_attachment` |
+| **Xray** | Xray test/precondition operations: search tests, get steps/preconditions, create or add to tests. | `commands/xray` → `jira_xray_*` (search, get details/steps/preconditions, create precondition, add to test) |
+| **Advanced** | Run a custom GET request to the JIRA API with auth. | `commands/advanced` → `jira_execute_request` |

.cursor/skills/jira-dmtools/commands/advanced/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: jira-dmtools-advanced
+description: Use when the user needs to run a custom GET request to the JIRA API with auth. Covers jira_execute_request. Run dmtools in the terminal.
+---
+
+# JIRA custom API request
+
+## When to use this skill
+
+Use when the user needs to:
+- Call a JIRA REST API endpoint that is not covered by other jira_* tools
+- Perform a custom GET request with the same authentication as dmtools (JIRA_BASE_PATH, JIRA_EMAIL, JIRA_API_TOKEN)
+
+## Commands
+
+| Tool | Purpose | Parameters |
+|------|---------|------------|
+| `jira_execute_request` | Custom HTTP GET to Jira API with auth | `url` (required) |
+
+## Steps
+
+1. Build the full JIRA API URL (e.g. `https://company.atlassian.net/rest/api/3/issue/PROJ-123?expand=changelog`). Base is typically from JIRA_BASE_PATH.
+2. Run `dmtools jira_execute_request --data '{"url":"https://..."}'`.
+3. Parse JSON (or other) stdout; check stderr on failure.
+
+## Examples
+
+```bash
+# Custom GET (e.g. issue with expand)
+dmtools jira_execute_request --data '{"url":"https://company.atlassian.net/rest/api/3/issue/PROJ-123?expand=changelog"}'
+```
+
+## Notes
+
+- Only GET is supported; no POST/PUT/DELETE. For other operations use the dedicated jira_* tools where possible.
+- URL must be reachable with the configured JIRA credentials (same host as JIRA_BASE_PATH typically).
+
+## Avoiding malformed API URLs
+
+`jira_execute_request` uses `--data` with a single `url` field. Ensure the JSON is valid and passed as a **single argument** (correct shell quoting); bad quoting can cause mangled URLs and 404s.

.cursor/skills/jira-dmtools/commands/attachments/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: jira-dmtools-attachments
+description: Use when the user needs to attach a file to a JIRA ticket or download an attachment. Covers jira_attach_file_to_ticket, jira_download_attachment. Run dmtools in the terminal.
+---
+
+# JIRA attachments
+
+## When to use this skill
+
+Use when the user wants to:
+- Attach a local file to a JIRA ticket (skipped if a file with the same name already exists)
+- Download an attachment from JIRA by URL to a local file
+
+## Commands
+
+| Tool | Purpose | Parameters |
+|------|---------|------------|
+| `jira_attach_file_to_ticket` | Attach file from path | `name`, `ticketKey`, `filePath` (required), `contentType` (optional) |
+| `jira_download_attachment` | Download by URL | `href` (required) |
+
+## Steps
+
+1. **Attach:** Have the ticket key, file path (absolute), and display name. Run `dmtools jira_attach_file_to_ticket --data '{"name":"doc.pdf","ticketKey":"PROJ-123","filePath":"/path/to/doc.pdf"}'`. Add `"contentType":"application/pdf"` if needed (default may be image/*).
+2. **Download:** Use the attachment href from ticket or search response: `dmtools jira_download_attachment --data '{"href":"https://company.atlassian.net/..."}'`.
+3. Parse stdout; check stderr on failure.
+
+## Examples
+
+```bash
+# Attach PDF
+dmtools jira_attach_file_to_ticket --data '{"name":"spec.pdf","ticketKey":"PROJ-123","filePath":"/tmp/spec.pdf","contentType":"application/pdf"}'
+
+# Attach image (contentType optional)
+dmtools jira_attach_file_to_ticket --data '{"name":"screenshot.png","ticketKey":"PROJ-123","filePath":"/tmp/screenshot.png"}'
+
+# Download
+dmtools jira_download_attachment --data '{"href":"https://company.atlassian.net/rest/api/3/attachment/12345/content"}'
+```
+
+## Notes
+
+- Attach only adds if no attachment with the same name exists on the ticket. Use absolute paths for `filePath`.
+- Download href is typically from the ticket's attachment list (Jira REST API or jira_get_ticket with attachments).
+
+## Avoiding malformed API URLs
+
+These commands use `--data` with JSON. Ensure the JSON is valid and passed as a **single argument** (correct shell quoting); bad quoting can cause mangled URLs and 404s.

.cursor/skills/jira-dmtools/commands/comments/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: jira-dmtools-comments
+description: Use when the user needs to add or read comments on a JIRA ticket. Covers jira_post_comment, jira_post_comment_if_not_exists, jira_get_comments. Run dmtools in the terminal.
+---
+
+# JIRA comments
+
+## When to use this skill
+
+Use when the user wants to:
+- Add a comment to a ticket
+- Add a comment only if it does not already exist (idempotent)
+- Read all comments on a ticket
+
+## Commands
+
+| Tool | Purpose | Parameters |
+|------|---------|------------|
+| `jira_post_comment` | Add comment (Jira markup supported) | `key`, `comment` (required) |
+| `jira_post_comment_if_not_exists` | Add only if comment not present | `key`, `comment` (required) |
+| `jira_get_comments` | Get all comments | `key` (required), `ticket` (optional) |
+
+## Steps
+
+1. Have the ticket key and comment text ready.
+2. To **add:** `dmtools jira_post_comment PROJ-123 "Comment text"` or `dmtools jira_post_comment --data '{"key":"PROJ-123","comment":"Comment text"}'`. Use `jira_post_comment_if_not_exists` with the same args when you want to avoid duplicates.
+3. To **read:** `dmtools jira_get_comments PROJ-123`.
+4. Parse JSON stdout; on error check stderr.
+
+## Examples
+
+```bash
+# Post comment (positional)
+dmtools jira_post_comment PROJ-123 "Deployed to staging."
+
+# Post comment (JSON, useful for long or multi-line)
+dmtools jira_post_comment --data '{"key":"PROJ-123","comment":"h2. Update\n* Item 1\n* Item 2"}'
+
+# Post only if not already present
+dmtools jira_post_comment_if_not_exists --data '{"key":"PROJ-123","comment":"Automated sync completed"}'
+
+# Get comments
+dmtools jira_get_comments PROJ-123
+```
+
+## Notes
+
+- Jira markup in comments: `h2.` for headings, `*text*` for bold, `{code}...{code}` for code, `*` for bullet lists.
+- Escape single quotes in JSON (e.g. `'"'"'` in shell) or use heredoc for complex content.
+
+## Avoiding malformed API URLs
+
+Prefer **positional** form for get and simple post: `dmtools jira_get_comments PROJ-123` and `dmtools jira_post_comment PROJ-123 "Comment text"`. Use `--data` only for long or multi-line comments. Ensure `--data` JSON is valid and passed as a single argument; bad quoting can cause mangled URLs and 404s. If you get a 404 or mangled path, retry with positional.

.cursor/skills/jira-dmtools/commands/fieldsdata/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: jira-dmtools-fieldsdata
+description: Use when the user needs JIRA field definitions or custom field IDs. Covers jira_get_fields, jira_get_field_custom_code, jira_get_all_fields_with_name. Run dmtools in the terminal.
+---
+
+# JIRA fields data
+
+## When to use this skill
+
+Use when the user wants to:
+- List all fields for a project
+- Resolve a human-readable field name to custom field ID (e.g. "Story Points" -> customfield_10021)
+- Get all field IDs that share a display name
+
+## Commands
+
+| Tool | Purpose | Parameters |
+|------|---------|------------|
+| `jira_get_fields` | All fields for project | `project` (required) |
+| `jira_get_field_custom_code` | Custom field ID for a name | `project`, `fieldName` (required) |
+| `jira_get_all_fields_with_name` | All field IDs with same name | `project`, `fieldName` (required) |
+
+## Steps
+
+1. Have the project key (e.g. `PROJ`).
+2. Run the needed command: `dmtools jira_get_fields PROJ`, or `jira_get_field_custom_code` / `jira_get_all_fields_with_name` with `--data`.
+3. Use the returned IDs in update/create/clear operations (e.g. customfield_10021 in `jira_update_field` or `jira_clear_field`).
+
+## Examples
+
+```bash
+dmtools jira_get_fields PROJ
+dmtools jira_get_field_custom_code --data '{"project":"PROJ","fieldName":"Story Points"}'
+dmtools jira_get_all_fields_with_name --data '{"project":"PROJ","fieldName":"Dependencies"}'
+```
+
+## Notes
+
+- Use `jira_get_field_custom_code` before updating or clearing a custom field by ID.
+- Some projects have multiple custom fields with the same display name; `jira_get_all_fields_with_name` returns all; `jira_update_all_fields_with_name` (ticket-update) updates all of them.
+- **Cached in jira.cfg:** Field data (e.g. from `jira_get_fields`, `jira_get_field_custom_code`) can be stored in `.dmtools/jira.cfg` per project. The verification script (run with `--project PROJ`) can populate this; agents may read `jira.cfg` for known field IDs when appropriate to avoid repeated API calls.
+
+## Avoiding malformed API URLs
+
+Prefer **positional** for single-param: `dmtools jira_get_fields PROJ`. For `jira_get_field_custom_code` and `jira_get_all_fields_with_name` use `--data`; ensure the JSON is valid and passed as a single argument (correct shell quoting). Bad quoting can cause mangled URLs and 404s.

.cursor/skills/jira-dmtools/commands/fix-versions/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: jira-dmtools-fix-versions
+description: Use when the user needs to list or change fix versions on JIRA tickets or project. Covers jira_get_fix_versions, jira_set_fix_version, jira_add_fix_version, jira_remove_fix_version. Run dmtools in the terminal.
+---
+
+# JIRA fix versions
+
+## When to use this skill
+
+Use when the user wants to:
+- List fix versions for a project
+- Set or add a fix version on a ticket (set replaces, add keeps existing)
+- Remove a fix version from a ticket
+
+## Commands
+
+| Tool | Purpose | Parameters |
+|------|---------|------------|
+| `jira_get_fix_versions` | List fix versions for project | `project` (required) |
+| `jira_set_fix_version` | Set fix version (replaces existing) | `key`, `fixVersion` (required) |
+| `jira_add_fix_version` | Add fix version (keep existing) | `key`, `fixVersion` (required) |
+| `jira_remove_fix_version` | Remove a fix version | `key`, `fixVersion` (required) |
+
+## Steps
+
+1. **List:** `dmtools jira_get_fix_versions PROJ` to see available version names.
+2. **Set (replace):** `dmtools jira_set_fix_version --data '{"key":"PROJ-123","fixVersion":"1.0.0"}'`.
+3. **Add (keep others):** `dmtools jira_add_fix_version --data '{"key":"PROJ-123","fixVersion":"1.1.0"}'`.
+4. **Remove:** `dmtools jira_remove_fix_version --data '{"key":"PROJ-123","fixVersion":"1.0.0"}'`.
+5. Parse stdout; check stderr on failure.
+
+## Examples
+
+```bash
+# List versions
+dmtools jira_get_fix_versions PROJ
+
+# Set single version (replaces any existing)
+dmtools jira_set_fix_version --data '{"key":"PROJ-123","fixVersion":"2.0.0"}'
+
+# Add version (multi-version ticket)
+dmtools jira_add_fix_version --data '{"key":"PROJ-123","fixVersion":"2.1.0"}'
+
+# Remove
+dmtools jira_remove_fix_version --data '{"key":"PROJ-123","fixVersion":"1.0.0"}'
+```
+
+## Notes
+
+- Fix version names must exist in the project; use `jira_get_fix_versions` first.
+- `set` clears other fix versions on the ticket; use `add` to keep them.
+
+## Avoiding malformed API URLs
+
+Prefer **positional** for list: `dmtools jira_get_fix_versions PROJ`. Set/add/remove use `--data`; ensure the JSON is valid and passed as a single argument. Bad quoting can cause mangled URLs and 404s.

.cursor/skills/jira-dmtools/commands/links-labels-priority/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: jira-dmtools-links-labels-priority
+description: Link issues, add labels, or set priority. jira_get_issue_link_types, jira_link_issues, jira_add_label, jira_set_priority.
+---
+
+# JIRA links, labels, priority
+
+Use when linking two issues, adding a label, or setting priority.
+
+**Commands:** `jira_get_issue_link_types` (no args), `jira_link_issues` (sourceKey, relationship, anotherKey), `jira_add_label` (key, label), `jira_set_priority` (key, priority).
+
+**Examples:**
+```bash
+dmtools jira_get_issue_link_types
+dmtools jira_link_issues --data '{"sourceKey":"PROJ-123","relationship":"blocks","anotherKey":"PROJ-456"}'
+dmtools jira_add_label PROJ-123 "mylabel"
+dmtools jira_set_priority --data '{"key":"PROJ-123","priority":"High"}'
+```
+
+Get valid relationship names from the first command. Priority values depend on project.
+
+**Avoiding malformed API URLs:** Prefer **positional** for add_label: `dmtools jira_add_label PROJ-123 "mylabel"`. For link_issues and set_priority use `--data`; ensure JSON is valid and passed as a single argument to avoid mangled URLs and 404s.

.cursor/skills/jira-dmtools/commands/metadata/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: jira-dmtools-metadata
+description: Use when the user needs JIRA project metadata: issue types, statuses, components. Covers jira_get_issue_types, jira_get_project_statuses, jira_get_components. For fields and field IDs see fieldsdata subskill. Run dmtools in the terminal.
+---
+
+# JIRA project metadata
+
+## When to use this skill
+
+Use when the user wants to:
+- List issue types for a project
+- List statuses for a project
+- List components for a project
+
+## Commands
+
+| Tool | Purpose | Parameters |
+|------|---------|------------|
+| `jira_get_issue_types` | Issue types for project | `project` (required) |
+| `jira_get_project_statuses` | Statuses for project | `project` (required) |
+| `jira_get_components` | Components for project | `project` (required) |
+
+## Steps
+
+1. Have the project key (e.g. `PROJ`).
+2. Run: `dmtools jira_get_issue_types PROJ`, `dmtools jira_get_project_statuses PROJ`, `dmtools jira_get_components PROJ`.
+3. Use the returned names in create/update or workflow (e.g. status names for transitions).
+
+## Examples
+
+```bash
+dmtools jira_get_issue_types PROJ
+dmtools jira_get_project_statuses PROJ
+dmtools jira_get_components PROJ
+```
+
+## Notes
+
+- For field definitions and custom field IDs use the fieldsdata subskill.
+- These commands use **positional** args only (`dmtools jira_get_issue_types PROJ` etc.); no `--data`, so URL-mangling from JSON is not a concern.
+- **Cached in jira.cfg:** Issue types, statuses, and components can be stored in `.dmtools/jira.cfg` per project. The verification script (run with `--project PROJ`) can populate this; agents may read `jira.cfg` for metadata when appropriate to avoid repeated API calls.