From 6f2cbf657cfff013783ce6a077df2df2b0552377 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ondr=CC=8Cej=20Hliba?= Date: Tue, 14 Apr 2026 10:35:14 +0200 Subject: [PATCH 1/2] chore: add shared ticket and PR workflow skills --- README.md | 3 + skills/pr-ready/README.md | 42 +++++++++ skills/pr-ready/SKILL.md | 126 +++++++++++++++++++++++++ skills/ticket-analysis/README.md | 46 +++++++++ skills/ticket-analysis/SKILL.md | 114 ++++++++++++++++++++++ skills/ticket-implementation/README.md | 47 +++++++++ skills/ticket-implementation/SKILL.md | 123 ++++++++++++++++++++++++ 7 files changed, 501 insertions(+) create mode 100644 skills/pr-ready/README.md create mode 100644 skills/pr-ready/SKILL.md create mode 100644 skills/ticket-analysis/README.md create mode 100644 skills/ticket-analysis/SKILL.md create mode 100644 skills/ticket-implementation/README.md create mode 100644 skills/ticket-implementation/SKILL.md diff --git a/README.md b/README.md index 5b7ae47..56e0a56 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,9 @@ Shared MCP setup guides and reusable agent skills for internal team use. ## Available Skills - `skills/mr-resolve/README.md` - interactive helper for GitLab MR review threads +- `skills/ticket-analysis/README.md` - analyze tickets from Jira, GitLab, or GitHub and map them to the codebase +- `skills/ticket-implementation/README.md` - implement tickets from Jira, GitLab, or GitHub with a lightweight analysis first +- `skills/pr-ready/README.md` - review, verify, branch, commit, and optionally push current work when explicitly requested ## Recommended Flow diff --git a/skills/pr-ready/README.md b/skills/pr-ready/README.md new file mode 100644 index 0000000..f1b0c13 --- /dev/null +++ b/skills/pr-ready/README.md @@ -0,0 +1,42 @@ +# pr-ready + +Review current work, run the required verification, prepare the branch, create a commit if the work is ready, and stop before push by default. + +## What It Does + +- reviews the current changes for bugs, regressions, and missing verification +- runs the required repository verification or the smallest meaningful checks +- fixes small directly related issues when appropriate +- creates or keeps a suitable branch +- creates a commit when the work is genuinely ready +- pushes only if the user explicitly asks for it + +## Requires + +- a git repository +- enough local tooling to run the repository verification commands + +## Install + +Install from the shared repo with `skills.sh`: + +```bash +npx skills add https://github.com/eManPrague/agent-tooling --skill pr-ready +``` + +## Example Prompts + +```text +Prepare the current changes for PR. Use pr-ready. +``` + +```text +Review, verify, commit, and push this branch if everything passes. Use pr-ready. +``` + +## Intended Behavior + +- review first +- verify before commit +- commit only when genuinely ready +- do not push unless explicitly asked diff --git a/skills/pr-ready/SKILL.md b/skills/pr-ready/SKILL.md new file mode 100644 index 0000000..9e926a4 --- /dev/null +++ b/skills/pr-ready/SKILL.md @@ -0,0 +1,126 @@ +--- +name: pr-ready +description: > + Review current work, run the required project verification, create or keep a + suitable branch, commit the ready changes, and stop before push with a clear + status summary. If the user explicitly asks for push, push only after review, + verification, branch preparation, and commit have succeeded. +--- + +# PR Ready + +Prepare current work for PR or MR review. + +## Input + +Accept one of: + +- current working tree +- current branch +- explicit scope from the user + +If the branch or scope is ambiguous, ask one short clarification question. + +## Workflow + +1. Inspect the current git state. +2. Review the changes for bugs, regressions, and missing verification. +3. Run the required verification for the repository. +4. Fix small review or verification issues when they are directly actionable. +5. If the work is ready, create or keep a suitable branch. +6. Commit the relevant changes. +7. If and only if the user explicitly asked for push, push the branch. +8. Report what succeeded, what failed, and what should happen next. + +## Review Rules + +- Default to a code review mindset. +- Look for bugs, behavioral regressions, risky edge cases, and missing validation. +- Keep the review practical. +- If you find a small fix that is clearly part of the same work, implement it. +- If you find a larger blocker, stop and report it instead of forcing a commit. + +## Verification Rules + +- Run the required verification for the repository if defined. +- Otherwise run the smallest meaningful verification for the changed area. +- Report every command you ran and whether it passed or failed. +- If verification fails, fix what is reasonable and rerun the relevant checks. +- If failures remain, do not create a misleading ready commit. + +## Branch Rules + +- If already on a sensible feature branch, keep it. +- If on the default branch, detached HEAD, or an obviously unsuitable branch, create a new branch first. +- If a new branch is needed, infer naming from repository conventions when possible. +- Otherwise use a short descriptive branch name. +- Do not push the branch unless the user explicitly asked for it. + +## Commit Rules + +- Commit only when the work is genuinely ready based on the review and verification outcome. +- Stage only the relevant changes. +- Do not include unrelated files. +- Infer commit message conventions from repository history or documented conventions when possible. +- Do not bypass hooks. +- Do not amend unless the user explicitly asks, or a hook modified files from the commit you just created and they need to be included. + +## Push Rules + +- Default behavior is no push. +- Push only when the user explicitly asks for it. +- Push only after the work is genuinely ready. +- Do not force push unless the user explicitly asks for it. +- Report whether push happened or was intentionally skipped. + +## Stop Conditions + +Stop without committing when: + +- review found a meaningful unresolved blocker +- required verification is still failing +- the work is not clear enough to commit safely + +In that case, report the blockers and the next action. + +## Output + +Return the result in this structure. + +### Review +- key findings or `No blocking findings` + +### Verification +- commands run +- pass/fail for each + +### Branch +- current branch kept or new branch created +- branch name + +### Commit +- commit created or not created +- commit hash and message if created + +### Ready To Push +- `Yes` or `No` + +### Push +- pushed or not pushed +- remote branch name if pushed +- if not pushed, state whether it was skipped by default or waiting for user confirmation + +### Failed Or Blocked +- remaining failures or blockers +- if none, say so explicitly + +### Next Actions +- short actionable list for the user + +## Constraints + +- Keep the flow simple. +- Do not push unless the user explicitly asks. +- Do not create a PR or MR unless the user asks. +- Do not commit unrelated changes. +- Ask at most one clarification question if the branch or scope is ambiguous. diff --git a/skills/ticket-analysis/README.md b/skills/ticket-analysis/README.md new file mode 100644 index 0000000..8197d3d --- /dev/null +++ b/skills/ticket-analysis/README.md @@ -0,0 +1,46 @@ +# ticket-analysis + +Analyze a ticket or issue from a URL or ID and return an implementation-ready analysis without changing code. + +## What It Does + +- detects the issue tracker from URL, ID, and repository context +- fetches the ticket using the best available MCP or local tooling +- maps the request to the current codebase +- returns a concrete analysis with the next recommended step + +## Requires + +Tracker access must already be configured. + +Supported sources include: + +- Atlassian MCP for Jira and Confluence +- GitLab MCP for GitLab issues +- GitHub MCP or `gh` for GitHub issues + +## Install + +Install from the shared repo with `skills.sh`: + +```bash +npx skills add https://github.com/eManPrague/agent-tooling --skill ticket-analysis +``` + +## Example Prompts + +```text +Analyze ticket MYPS-1755 +``` + +```text +Analyze this issue and tell me whether code changes are needed: +https://pplcz.atlassian.net/browse/MYPS-1755 +``` + +## Intended Behavior + +- analyze first +- fetch from the best available tracker source +- stay code-aware +- do not modify code diff --git a/skills/ticket-analysis/SKILL.md b/skills/ticket-analysis/SKILL.md new file mode 100644 index 0000000..7a006f9 --- /dev/null +++ b/skills/ticket-analysis/SKILL.md @@ -0,0 +1,114 @@ +--- +name: ticket-analysis +description: > + Analyze a ticket or issue from a URL or ID, detect the tracking system, + fetch the ticket using the best available MCP or local tooling, map it to the + current codebase, and return an implementation-ready analysis without changing + code. Use when the user asks to analyze a ticket, issue, bug, task, or pasted + tracker URL before implementation. +--- + +# Ticket Analysis + +Analyze a ticket before implementation. + +## Input + +Accept one of: + +- full Jira, GitLab, or GitHub issue URL +- tracker-specific key or ID like `MYPS-1755` +- plain identifier when the tracker is obvious from repository context + +If the source is ambiguous, ask one short clarification question. + +## Workflow + +1. Determine the issue tracker. +2. Fetch the ticket from the best available source. +3. Search the repo for the relevant code. +4. Read only the files needed to understand the current behavior. +5. Return an implementation-ready analysis. + +## Tracker Detection + +Resolve the source in this order: + +1. If the user pasted a full URL, use that platform. +2. If the ticket format is obvious, use it. +3. Otherwise inspect project context for issue tracking hints: + - repository docs, CI, PR templates, or scripts + - configured MCP servers or available MCP tools +4. If still ambiguous, ask one short clarification question. + +Do not guess between unrelated systems for plain numeric IDs. + +## Fetch Rules + +Prefer MCP for the matching platform when available. + +### Jira / Confluence + +- Use Atlassian MCP when available. +- If the project context clearly points to a single Atlassian site, use that site directly. +- If the ticket references a Confluence page that matters for implementation, fetch that too. + +### GitLab + +- Use GitLab MCP when available. +- Fetch the issue body first. +- Fetch discussions only when the body is not enough. + +### GitHub + +- Use GitHub MCP if available. +- Otherwise use `gh` via Bash in read-only mode. + +## Output + +Return the result in this structure. + +### Ticket +- source +- identifier +- title +- status + +### Problem +- current behavior or request +- desired outcome +- why it matters + +### Acceptance Criteria +- explicit criteria from the ticket +- inferred criteria needed for a correct outcome + +### Relevant Code +- files, functions, configs, or modules that appear to own the behavior +- one short note per reference + +### Proposed Approach +- smallest correct implementation or investigation path +- whether code changes are needed +- whether the ticket is implementation-ready + +### Risks +- likely regressions +- deployment, infra, data, or config concerns +- test gaps + +### Open Questions +- only blockers or material ambiguities +- if none, say so explicitly + +### Next Step +- `Implement change` +- `Investigate further` +- `Provide findings only` + +## Constraints + +- Do not change code. +- Do not create commits, branches, or tickets. +- Do not over-search the repo. +- Ask at most one clarification question if needed. diff --git a/skills/ticket-implementation/README.md b/skills/ticket-implementation/README.md new file mode 100644 index 0000000..420f1e7 --- /dev/null +++ b/skills/ticket-implementation/README.md @@ -0,0 +1,47 @@ +# ticket-implementation + +Implement a ticket or issue from a URL or ID with a lightweight analysis first and code changes only when they are actually needed. + +## What It Does + +- detects the issue tracker from URL, ID, and repository context +- fetches the ticket using the best available MCP or local tooling +- analyzes the request before changing code +- implements the smallest correct change when needed +- stops at findings only when no code change is required + +## Requires + +Tracker access must already be configured. + +Supported sources include: + +- Atlassian MCP for Jira and Confluence +- GitLab MCP for GitLab issues +- GitHub MCP or `gh` for GitHub issues + +## Install + +Install from the shared repo with `skills.sh`: + +```bash +npx skills add https://github.com/eManPrague/agent-tooling --skill ticket-implementation +``` + +## Example Prompts + +```text +Implement ticket MYPS-1755 +``` + +```text +Fix this issue: +https://pplcz.atlassian.net/browse/MYPS-1755 +``` + +## Intended Behavior + +- analyze first +- implement only when needed +- keep changes minimal +- do not commit or push unless explicitly asked diff --git a/skills/ticket-implementation/SKILL.md b/skills/ticket-implementation/SKILL.md new file mode 100644 index 0000000..170e047 --- /dev/null +++ b/skills/ticket-implementation/SKILL.md @@ -0,0 +1,123 @@ +--- +name: ticket-implementation +description: > + Implement a ticket or issue from a URL or ID using the detected tracking + system, with a small analysis first and code changes only when they are + actually needed. Use when the user asks to implement or fix a ticket, issue, + bug, or pasted tracker URL. +--- + +# Ticket Implementation + +Implement a ticket end-to-end with a lightweight analysis first. + +## Input + +Accept one of: + +- full Jira, GitLab, or GitHub issue URL +- tracker-specific key or ID like `MYPS-1755` +- plain identifier when the tracker is obvious from repository context + +If the source is ambiguous, ask one short clarification question. + +## Workflow + +1. Determine the issue tracker. +2. Fetch the ticket from the best available source. +3. Understand the request and locate the relevant code. +4. Decide whether code or config changes are actually needed. +5. If yes, implement the smallest correct change. +6. Run the required verification for the repository. +7. Return a concise implementation summary. + +If the ticket turns out to require only investigation or findings, stop after the analysis and explain that no code change is needed. + +## Tracker Detection + +Resolve the source in this order: + +- URL first +- obvious ticket format second +- then project context and available MCP tools +- otherwise ask one short clarification question + +## Fetch Rules + +Prefer MCP for the matching platform when available. + +### Jira / Confluence + +- Use Atlassian MCP when available. +- Fetch linked Confluence pages only when needed for implementation. + +### GitLab + +- Use GitLab MCP when available. +- Pull in discussions only when the main description is not enough. + +### GitHub + +- Use GitHub MCP if available. +- Otherwise use `gh` in read-only mode unless the user asks for write actions. + +## Implementation Rules + +- Start with a short analysis, not a long planning phase. +- Make the smallest correct change. +- Follow repository instructions and local code patterns. +- Do not add broad refactors unless the ticket truly requires them. +- Do not commit, push, or update the ticket unless the user asks. + +## If No Code Change Is Needed + +Return: + +- what you found +- why no code change is needed +- what the next human or process step should be + +## Output + +When code changed, return: + +### Ticket +- source +- identifier +- title + +### What Changed +- short summary of the implemented fix + +### Files +- touched files with one short note each + +### Verification +- commands run +- pass/fail result +- anything skipped and why + +### Risks +- residual concerns or follow-ups + +When no code changed, return: + +### Ticket +- source +- identifier +- title + +### Findings +- concise result of the investigation + +### Why No Change Was Made +- exact reason + +### Next Step +- what should happen next + +## Constraints + +- Keep the flow simple. +- Ask at most one clarification question if the source or intent is ambiguous. +- Do not create commits, branches, or tracker updates unless requested. From 1d3cff30ff01b367f5c11021625b04baa8c433e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ondr=CC=8Cej=20Hliba?= Date: Tue, 14 Apr 2026 10:46:54 +0200 Subject: [PATCH 2/2] chore: add Atlassian Jira MCP setup guide --- README.md | 6 ++- mcps/jira/README.md | 126 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 130 insertions(+), 2 deletions(-) create mode 100644 mcps/jira/README.md diff --git a/README.md b/README.md index 56e0a56..32c26da 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ Shared MCP setup guides and reusable agent skills for internal team use. ## Available MCP Guides - `mcps/gitlab/README.md` - GitLab MCP setup for supported agents +- `mcps/jira/README.md` - Atlassian Rovo MCP setup for Jira support in supported agents ## Available Skills @@ -21,5 +22,6 @@ Shared MCP setup guides and reusable agent skills for internal team use. ## Recommended Flow 1. Set up GitLab MCP first using `mcps/gitlab/README.md` -2. Install the skill from `skills/mr-resolve/` -3. Use the skill on merge requests with unresolved review feedback +2. Set up Jira MCP using `mcps/jira/README.md` if you want Jira-backed ticket workflows +3. Install the skill from `skills/mr-resolve/` +4. Use the skill on merge requests with unresolved review feedback diff --git a/mcps/jira/README.md b/mcps/jira/README.md new file mode 100644 index 0000000..4fa3100 --- /dev/null +++ b/mcps/jira/README.md @@ -0,0 +1,126 @@ +# Jira MCP + +Setup guide for connecting your agent to Atlassian Rovo MCP for Jira access. + +## Supports + +- OpenCode +- Codex +- Claude Code +- Cursor +- JetBrains AI Assistant + +## Prerequisites + +- Atlassian Cloud site with Jira enabled +- Access to the Atlassian site you want to use +- Node.js 18+ +- `npx` +- A browser for the OAuth login flow + +## Server Endpoint + +Use Atlassian's remote MCP server through `mcp-remote`: + +```text +https://mcp.atlassian.com/v1/mcp +``` + +The first login is handled through Atlassian OAuth in the browser. No local PAT is required for the basic setup below. + +## Codex + +Add to `~/.codex/config.toml`: + +```toml +[mcp_servers.atlassian] +command = "npx" +args = ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/mcp"] +``` + +## OpenCode + +Add to `~/.config/opencode/opencode.json` or `opencode.jsonc`: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "mcp": { + "atlassian": { + "type": "local", + "command": ["npx", "-y", "mcp-remote", "https://mcp.atlassian.com/v1/mcp"], + "enabled": true + } + } +} +``` + +## Claude Code + +Add to `~/.claude.json` for user scope or `.mcp.json` in the repo for project scope: + +```json +{ + "mcpServers": { + "atlassian": { + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/mcp"] + } + } +} +``` + +## Cursor + +Add to `~/.cursor/mcp.json` for global scope or `.cursor/mcp.json` for project scope: + +```json +{ + "mcpServers": { + "atlassian": { + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/mcp"] + } + } +} +``` + +## JetBrains AI Assistant + +In the IDE: + +1. Open `Settings` +2. Go to `Tools | AI Assistant | Model Context Protocol (MCP)` +3. Click `Add` +4. Choose `STDIO` +5. Paste: + +```json +{ + "mcpServers": { + "atlassian": { + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/mcp"] + } + } +} +``` + +## Verify + +After restart, verify with two prompts: + +- `Find my recent Jira issues` +- `Open issue ABC-123 and summarize it` + +Expected result: + +- the browser opens an Atlassian login/consent flow on first use +- Jira issues can be searched and read after login + +## Notes + +- This uses Atlassian's hosted MCP endpoint, proxied by `mcp-remote` +- Access is limited by the signed-in Atlassian user's permissions +- The same server can also expose Confluence and other Atlassian products, but this guide is focused on Jira support for our ticket skills +- If your org blocks MCP usage, an Atlassian admin may need to allow it first