oprogramadorreal/optimus-claude / skills/jira
jira
VerifiedFetches a JIRA issue via a configured MCP server and distills it into a structured task file at docs/jira/<KEY>.md that downstream skills auto-detect. Analyzes the codebase to surface missing criteria, scope, and risks; optionally writes an analysis comment or implementation tickets back to JIRA after explicit confirmation. Re-runs reconcile the local file instead of regenerating. Guides MCP setup if none is configured.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 6.9 KB |
| SKILL.md | skill md | 6.3 KB |
| agents/openai.yaml | config | 198 B |
| references/jira-codebase-analysis.md | markdown | 6.9 KB |
| references/jira-context-extraction.md | markdown | 8.0 KB |
| references/jira-implementation-tickets.md | markdown | 6.3 KB |
| references/jira-refresh.md | markdown | 7.6 KB |
| references/jira-setup.md | markdown | 3.0 KB |
| references/plan-mode-prompt.md | markdown | 1.0 KB |
README.md
View on GitHub# optimus:jira
A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill that fetches a JIRA issue and distills it into structured task context for AI-assisted development. It saves the result to `docs/jira/<ISSUE-KEY>.md`, analyzes the codebase to surface missing criteria, scope, and risks, and can optionally write an analysis comment or implementation tickets back to JIRA — always behind explicit confirmation.
## Features
- **Automatic MCP detection** — finds your configured JIRA MCP server (Atlassian Rovo, sooperset/mcp-atlassian, or generic) and guides first-time setup if none exists
- **Search or fetch** — fetch by key (`PROJ-123`), search your assigned issues, or browse by project
- **Structured distillation** — goal, acceptance criteria, context (sprint, links, subtasks), and key decisions from comments
- **Codebase impact analysis** — compares the requirements against actual code to surface missing criteria, scope (Simple/Medium/Complex), and risks
- **Optional JIRA enrichment** — posts an analysis comment, and for Complex scope can spawn linked implementation tickets (opt-in, default off)
- **Refresh-aware re-runs** — re-running on the same key reconciles the local file with JIRA, preserving prior enrichment and checking implementation tickets for drift
- **MCP safety** — read-only tool enforcement during extraction; writes happen only at explicit confirmation gates
- **Cross-skill flow** — recommends the next optimus skill based on assessed complexity
## Quick Start
This skill is part of the [optimus](https://github.com/oprogramadorreal/optimus-claude) plugin. See the [main README](../../README.md) for installation.
A JIRA MCP server must be configured — in Claude Code, the skill guides setup interactively if none is detected. Under Codex, configure a compatible server in Codex first, then invoke `$optimus:jira`; the setup commands below configure Claude Code only. Under Codex, the plan-mode handoff uses brainstorm's shared Codex branch instead of Claude's plan-mode steps; see the [Codex support matrix](../../README.md#using-with-openai-codex).
**Atlassian Rovo** (official, JIRA Cloud, OAuth):
```bash
claude mcp add --transport http --scope user atlassian https://mcp.atlassian.com/v1/mcp
```
Requires Rovo MCP Server enabled by your org admin (`admin.atlassian.com → Apps → AI settings`). Then run `/mcp` in a Claude Code session to authenticate — no JIRA tools appear before that. Use `--transport http` — the older SSE transport is deprecated and flaky on Windows.
**sooperset/mcp-atlassian** (community, JIRA Cloud or Server/Data Center):
```bash
claude mcp add-json mcp-atlassian '{
"command": "uvx",
"args": [
"mcp-atlassian",
"--jira-url=https://YOUR-COMPANY.atlassian.net",
"--jira-username=your.email@company.com",
"--jira-token=YOUR_API_TOKEN"
]
}'
```
Get an API token at https://id.atlassian.com/manage-profile/security/api-tokens. For Server/DC, use `--jira-personal-token` instead of username/token.
## Usage
- `/optimus:jira PROJ-123` — fetch a specific issue by key
- `/optimus:jira` — search your assigned issues or browse by project
The skill fetches the issue, presents a structured task (goal, acceptance criteria, context, key decisions) for your confirmation, saves it to `docs/jira/<ISSUE-KEY>.md`, analyzes the codebase against it, and recommends the next skill. Re-running on the same key refreshes the local file from JIRA instead of regenerating it.
## When to Use
- **Before starting work** — get structured context before coding
- **Before TDD** — acceptance criteria map directly to testable behaviors
- **To enrich issues** — post codebase analysis findings back to JIRA
Skip it if your team doesn't use JIRA, or the task is already clear from conversation context.
## Writing JIRA Tickets for AI-Assisted Development
Explicit acceptance criteria in the ticket = accurate implementation; vague prose = the AI guesses what "done" means. A description template for ticket authors:
```
## Goal
[One sentence: what capability or fix, and why it matters.]
## Acceptance Criteria
1. [Verb + observable outcome — e.g., "Returns 200 with user profile when valid token is provided"]
2. [One behavior per criterion, independently testable]
3. [Include error/edge cases — e.g., "Returns 400 when token is expired"]
## Technical Notes (optional)
- [Constraints, dependencies, performance requirements]
## Out of Scope (optional)
- [What this ticket explicitly does NOT cover]
```
Given/When/Then criteria are extracted as-is (translated to English for non-English issues). Use comments for decisions that affect implementation ("We chose JWT over sessions because...") — the skill distills them into a Key Decisions section and ignores status updates.
## Relationship to Other Skills
The recommended next command names the saved `docs/jira/<ISSUE-KEY>.md` explicitly — its path, its key, or a refactor scope drawn from it. `/optimus:tdd` and `/optimus:brainstorm` also auto-detect the file.
| Task complexity | Workflow |
|----------------|----------|
| Simple | `/optimus:jira PROJ-123` → `/optimus:tdd docs/jira/PROJ-123.md` |
| Medium | `/optimus:jira PROJ-123` → plan mode (jira generates the prompt) → `/optimus:tdd` |
| Complex | `/optimus:jira PROJ-123` → `/optimus:brainstorm PROJ-123` → plan mode → `/optimus:tdd` |
| Tech debt | `/optimus:jira PROJ-123` → `/optimus:refactor "<scope>"` |
The skill recommends the right path based on codebase-assessed complexity. It never creates branches or writes code — its only side effects are the task file under `docs/jira/` and the opt-in JIRA writes.
In spec-driven-development terms, `/optimus:jira` is the supported path for PM-authored content (a JIRA issue, or an external PRD pasted into one), distilling it into engineering-shaped task context. See [`references/sdd-mapping.md`](../../references/sdd-mapping.md).
## Skill Structure
| File | Purpose |
|------|---------|
| `SKILL.md` | The step-by-step workflow |
| `references/jira-context-extraction.md` | MCP server detection, tool names, safety rules, fetch and output procedure |
| `references/jira-setup.md` | First-time MCP server setup (loaded only when no server is detected) |
| `references/jira-codebase-analysis.md` | Codebase impact analysis, scope assessment, task-file enrichment |
| `references/jira-refresh.md` | Re-run reconciliation — diff JIRA against the local file, preserve enrichment |
| `references/jira-implementation-tickets.md` | Opt-in implementation-ticket creation for Complex scope |
| `references/plan-mode-prompt.md` | Medium-route plan-mode prompt, built on brainstorm's shared `references/plan-mode-handoff.md` |
## Requirements
- Optimus installed in a [supported host](../../README.md#supported-hosts-and-versions)
- A JIRA MCP server configured in your host — the skill guides setup in Claude Code; in Codex, configure it yourself first
## License
[MIT](../../LICENSE)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |