| name | cowork-with-jira |
| description | Use when the user works with or mentions Jira issues, tickets, stories, bugs, tasks, sprints, epics, or any agile workflow |
| argument-hint | [PROJ-123 or description] |
| allowed-tools | Read, Glob, Grep, Bash, Agent, AskUserQuestion |
Jira Workflow
Agile Jira workflow for Claude Code via the Atlassian Rovo MCP server.
Prerequisites
Requires globally installed Atlassian MCP server (named atlassian). If not set up, run /cowork-with:cowork-with-onboarding.
Issue Conventions
Title Format
No type prefix. Jira tracks issue types natively — never prefix with [Feature], Bug:, etc.
Description Format
Plain text only. Jira does NOT render Markdown — no ##, **, - [ ], or backtick fences. Use Jira wiki markup or plain text with simple line breaks.
Every issue description MUST include these sections:
Background
Why this issue exists. What problem it solves. Any relevant context.
Acceptance Criteria
- Specific, testable criterion
- Another criterion
Do not skip Acceptance Criteria. Even for small tasks, at least one criterion is required.
Issue Type Selection
Issue type names are localized — a project may use "Bug", "缺陷 Bug", "バグ", etc. Always use the explorer agent to call getJiraProjectIssueTypesMetadata first and use the exact type name returned.
| Intent | Jira Type | Label | When to use |
|---|
| New functionality | Story | story | User-facing feature or capability |
| Bug fix | Bug | bug | Something is broken |
| Technical work | Task | task | Maintenance, config, dependencies, refactoring |
| Research | Task | spike | Investigation or spike |
| Documentation | Task | documentation | Docs changes |
| Large initiative | Epic | epic | Groups 3+ related stories |
| Subtask | Sub-task | subtask | Discrete piece of a parent story |
Additional labels for special categories: tech-debt. If the project has existing label conventions (check recent issues), follow those instead.
Workflow Rules
Default Assignment
Always assign to @me unless the user specifies a different assignee.
User Lookup
When assigning to someone other than @me, use the explorer agent to call lookupJiraAccountId to resolve their name or email to an account ID before creating or editing the issue.
Default Priority
Always set Medium unless specified.
| Priority | When to use |
|---|
| Highest | Production down, data loss, security vulnerability |
| High | Blocks other work, major user-facing issue |
| Medium | Default — standard work |
| Low | Nice-to-have, minor polish |
| Lowest | Cosmetic, trivial |
Status Lifecycle
To Do → In Progress → In Review → Done
| Status | When to transition |
|---|
| To Do | Issue created, ready to work on |
| In Progress | User starts working on it |
| In Review | Code submitted for review (if status exists) |
| Done | Work finished and verified |
Proactive transitions: When context makes it obvious (e.g., user says "I'm working on PROJ-42"), transition to In Progress without asking.
Custom workflow handling: If a transition fails, use the explorer agent to call getTransitionsForJiraIssue to inspect available transitions and pick the closest match. Report the actual status name to the user.
Tool Strategy
ALL MCP read tool calls MUST go through the `explorer` agent. The main model MUST NOT call any MCP read tool directly — always spawn the `explorer` agent to do it. This is mandatory because the explorer agent enforces correct parameter types and names. Calling MCP read tools directly from the main model is forbidden.
Spawn via: Agent tool → name: "explorer" (the plugin ships agents/explorer.md — haiku model, read-only: MCP reads + codebase + git).
| Task | Who |
|---|
| Read from Jira (search, view, metadata) | explorer agent |
| Read git/gh context, explore codebase | explorer agent |
| Draft issue content (title, description, criteria) | Main model |
| Preview to user and get confirmation | Main model |
| Write to Jira (create, edit, transition, comment) | Main model |
MCP Tools
Read (explorer agent):
getJiraIssue — read a single issue (param: issueIdOrKey)searchJiraIssuesUsingJql — search issues with JQL (param: maxResults must be number, not string)getVisibleJiraProjects — list projectsgetJiraProjectIssueTypesMetadata — issue types for a project (param: projectIdOrKey)getJiraIssueTypeMetaWithFields — field metadata for an issue type (param: projectIdOrKey, issueTypeId)getTransitionsForJiraIssue — available status transitionsgetJiraIssueRemoteIssueLinks — remote links on an issuelookupJiraAccountId — resolve user name/email to account IDatlassianUserInfo — current authenticated user infojiraRead — generic Jira REST API read (fallback for endpoints not covered above)search — cross-service Atlassian search (searches Jira + Confluence together)
Write (main model, after user confirmation):
createJiraIssue — create a new issue (param: issueTypeName — NOT issueType; labels is array of strings)editJiraIssue — update an existing issue (param: issueIdOrKey; fields must be object, not JSON string)transitionJiraIssue — change issue statusaddCommentToJiraIssue — add a commentaddWorklogToJiraIssue — log work time
Issue Creation Flow
1. `explorer` agent → Fetch project context (ALL in one batch, parallel where possible):
a. getJiraProjectIssueTypesMetadata (exact localized type names)
b. getJiraIssueTypeMetaWithFields (ALL required fields incl. custom)
c. searchJiraIssuesUsingJql "sprint in openSprints()" (active sprint name + goal)
2. Main model → Compare required fields vs. known values
If ANY required field is missing → ask user via AskUserQuestion BEFORE drafting
3. Main model → Present active sprint to user:
Show sprint name, goal, and date range
Ask: assign to this sprint, or leave unassigned?
4. `explorer` agent → Read git context + search codebase if needed for context
5. Main model → Draft title, description (plain text!), acceptance criteria
6. Main model → Preview FULL draft to user via AskUserQuestion (HARD-GATE below)
Include sprint assignment in preview if selected
7. Main model → Create issue after user approves (createJiraIssue)
8. Main model → Offer to create a feature branch (git checkout -b feat/PROJ-123-slug)
Step 1c is critical — sprint context must ALWAYS be fetched before drafting. If the JQL returns no active sprint, inform the user that no sprint is active and proceed without sprint assignment.
Required Fields & Custom Fields
Step 1b reads ALL required fields for the chosen issue type. Before drafting:
- List every required field and check which ones already have values (from user input or defaults like assignee, priority)
- If any required field has no value (especially custom fields like
customfield_10079), use AskUserQuestion to ask the user for the missing values. Do NOT attempt to create the issue with missing required fields.
- Include discovered required fields in the final confirmation preview (Step 7)
Fallback when creation still fails: If createJiraIssue rejects due to a required field despite passing it via additionalFields, create as Task first (fewer required fields), then use editJiraIssue with fields (object, not string) to change issue type and set the custom field. Report the workaround to the user.
Before creating or updating issue content, you MUST use `AskUserQuestion` to present a structured confirmation. Show the full draft (title, type, sprint, description, labels, priority, and all required fields) in the `markdown` preview field. Options: "Submit" (Recommended), "Edit", "Cancel". Do NOT call any Jira write tool without explicit user approval via this confirmation. This is NOT optional — text-based confirmation ("确认创建？") does NOT satisfy this gate. You MUST call the `AskUserQuestion` tool. Status-only transitions skip this gate.
Agile Workflow & Git Integration
For epics, sprints, sub-tasks, post-commit hook, and commit message format, see reference.md in this skill directory.
Key rules (always apply):
- Sprints: Never auto-add issues to a sprint — let the user decide
- Branch names: Include the issue key —
feat/PROJ-123-slug or fix/PROJ-123-slug. Jira auto-tracks branches containing the issue key.
- Commit messages:
[PROJ-123] commit message when related to a task
- Post-commit: Hook auto-triggers task closure check; use
explorer agent to find related in-progress tasks
Cross-Skill Integration
- After reading task context, offer
/superpowers:brainstorming to explore implementation approaches.
- If implementation reveals undocumented product behavior, suggest
/cowork-with:cowork-with-wiki to create or update documentation.
- If a Jira issue contains a Figma URL, use
/cowork-with:cowork-with-figma to read design context before implementing.
Limitations
See reference.md for full list. Key: no sprint management, no issue links, no attachments via MCP.
