From be0c56957b5a61071be032b6221995f8fd8eb14a Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Thu, 2 Apr 2026 17:51:03 -0700 Subject: [PATCH] feat: add jira integration workflow --- AGENTS.md | 6 +- README.md | 10 +- README.zh-CN.md | 2 +- WORKING-CONTEXT.md | 2 + commands/jira.md | 106 +++++++++++ docs/zh-CN/AGENTS.md | 6 +- docs/zh-CN/README.md | 10 +- manifests/install-modules.json | 1 + mcp-configs/mcp-servers.json | 10 ++ skills/jira-integration/SKILL.md | 293 +++++++++++++++++++++++++++++++ 10 files changed, 429 insertions(+), 17 deletions(-) create mode 100644 commands/jira.md create mode 100644 skills/jira-integration/SKILL.md diff --git a/AGENTS.md b/AGENTS.md index 14ac0593..be028c2b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Everything Claude Code (ECC) — Agent Instructions -This is a **production-ready AI coding plugin** providing 38 specialized agents, 154 skills, 71 commands, and automated hook workflows for software development. +This is a **production-ready AI coding plugin** providing 38 specialized agents, 155 skills, 72 commands, and automated hook workflows for software development. **Version:** 1.9.0 @@ -146,8 +146,8 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat ``` agents/ — 38 specialized subagents -skills/ — 154 workflow skills and domain knowledge -commands/ — 71 slash commands +skills/ — 155 workflow skills and domain knowledge +commands/ — 72 slash commands hooks/ — Trigger-based automations rules/ — Always-follow guidelines (common + per-language) scripts/ — Cross-platform Node.js utilities diff --git a/README.md b/README.md index 01a42d47..5aed1747 100644 --- a/README.md +++ b/README.md @@ -225,7 +225,7 @@ For manual install instructions see the README in the `rules/` folder. When copy /plugin list everything-claude-code@everything-claude-code ``` -**That's it!** You now have access to 38 agents, 154 skills, and 71 legacy command shims. +**That's it!** You now have access to 38 agents, 155 skills, and 72 legacy command shims. ### Multi-model commands require additional setup @@ -1119,8 +1119,8 @@ The configuration is automatically detected from `.opencode/opencode.json`. | Feature | Claude Code | OpenCode | Status | |---------|-------------|----------|--------| | Agents | PASS: 38 agents | PASS: 12 agents | **Claude Code leads** | -| Commands | PASS: 71 commands | PASS: 31 commands | **Claude Code leads** | -| Skills | PASS: 154 skills | PASS: 37 skills | **Claude Code leads** | +| Commands | PASS: 72 commands | PASS: 31 commands | **Claude Code leads** | +| Skills | PASS: 155 skills | PASS: 37 skills | **Claude Code leads** | | Hooks | PASS: 8 event types | PASS: 11 events | **OpenCode has more!** | | Rules | PASS: 29 rules | PASS: 13 instructions | **Claude Code leads** | | MCP Servers | PASS: 14 servers | PASS: Full | **Full parity** | @@ -1228,8 +1228,8 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e | Feature | Claude Code | Cursor IDE | Codex CLI | OpenCode | |---------|------------|------------|-----------|----------| | **Agents** | 38 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 | -| **Commands** | 71 | Shared | Instruction-based | 31 | -| **Skills** | 154 | Shared | 10 (native format) | 37 | +| **Commands** | 72 | Shared | Instruction-based | 31 | +| **Skills** | 155 | Shared | 10 (native format) | 37 | | **Hook Events** | 8 types | 15 types | None yet | 11 types | | **Hook Scripts** | 20+ scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks | | **Rules** | 34 (common + lang) | 34 (YAML frontmatter) | Instruction-based | 13 instructions | diff --git a/README.zh-CN.md b/README.zh-CN.md index 6c7ac3d4..155f4aa5 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -106,7 +106,7 @@ cp -r everything-claude-code/rules/perl ~/.claude/rules/ /plugin list everything-claude-code@everything-claude-code ``` -**完成！** 你现在可以使用 38 个代理、154 个技能和 71 个命令。 +**完成！** 你现在可以使用 38 个代理、155 个技能和 72 个命令。 ### multi-* 命令需要额外配置 diff --git a/WORKING-CONTEXT.md b/WORKING-CONTEXT.md index 37891d6d..5cac73db 100644 --- a/WORKING-CONTEXT.md +++ b/WORKING-CONTEXT.md @@ -87,6 +87,8 @@ Keep this file detailed for only the current sprint, blockers, and next actions. - 2026-04-02: `ECC-Tools/main` shipped `9566637` (`fix: prefer commit lookup over git ref resolution`). The PR-analysis fire is now fixed in the app repo by preferring explicit commit resolution before `git.getRef`, with regression coverage for pull refs and plain branch refs. Mirrored public tracking issue `#1184` in this repo was closed as resolved upstream. - 2026-04-02: Direct-ported the clean native-support core of `#1043` into `main`: `agents/csharp-reviewer.md`, `skills/dotnet-patterns/SKILL.md`, and `skills/csharp-testing/SKILL.md`. This fills the gap between existing C# rule/docs mentions and actual shipped C# review/testing guidance. - 2026-04-02: Direct-ported the clean native-support core of `#1055` into `main`: `agents/dart-build-resolver.md`, `commands/flutter-build.md`, `commands/flutter-review.md`, `commands/flutter-test.md`, `rules/dart/*`, and `skills/dart-flutter-patterns/SKILL.md`. The skill paths were wired into the current `framework-language` module instead of replaying the older PR's separate `flutter-dart` module layout. +- 2026-04-02: Closed `#1081` after diff audit. The PR only added vendor-marketing docs for an external X/Twitter backend (`Xquik` / `x-twitter-scraper`) to the canonical `x-api` skill instead of contributing an ECC-native capability. +- 2026-04-02: Direct-ported the useful Jira lane from `#894`, but sanitized it to match current supply-chain policy. `commands/jira.md`, `skills/jira-integration/SKILL.md`, and the pinned `jira` MCP template in `mcp-configs/mcp-servers.json` are in-tree, while the skill no longer tells users to install `uv` via `curl | bash`. `jira-integration` is classified under `operator-workflows` for selective installs. - 2026-04-02: Closed `#1125` after full diff audit. The bundle/skill-router lane hardcoded many non-existent or non-canonical surfaces and created a second routing abstraction instead of a small ECC-native index layer. - 2026-04-02: Closed `#1124` after full diff audit. The added agent roster was thoughtfully written, but it duplicated the existing ECC agent surface with a second competing catalog (`dispatch`, `explore`, `verifier`, `executor`, etc.) instead of strengthening canonical agents already in-tree. - 2026-04-02: Closed the full Argus cluster `#1098`, `#1099`, `#1100`, `#1101`, and `#1102` after full diff audit. The common failure mode was the same across all five PRs: external multi-CLI dispatch was treated as a first-class runtime dependency of shipped ECC surfaces. Any useful protocol ideas should be re-ported later into ECC-native orchestration, review, or reflection lanes without external CLI fan-out assumptions. diff --git a/commands/jira.md b/commands/jira.md new file mode 100644 index 00000000..4830bf22 --- /dev/null +++ b/commands/jira.md @@ -0,0 +1,106 @@ +--- +description: Retrieve a Jira ticket, analyze requirements, update status, or add comments. Uses the jira-integration skill and MCP or REST API. +--- + +# Jira Command + +Interact with Jira tickets directly from your workflow — fetch tickets, analyze requirements, add comments, and transition status. + +## Usage + +``` +/jira get # Fetch and analyze a ticket +/jira comment # Add a progress comment +/jira transition # Change ticket status +/jira search # Search issues with JQL +``` + +## What This Command Does + +1. **Get & Analyze** — Fetch a Jira ticket and extract requirements, acceptance criteria, test scenarios, and dependencies +2. **Comment** — Add structured progress updates to a ticket +3. **Transition** — Move a ticket through workflow states (To Do → In Progress → Done) +4. **Search** — Find issues using JQL queries + +## How It Works + +### `/jira get ` + +1. Fetch the ticket from Jira (via MCP `jira_get_issue` or REST API) +2. Extract all fields: summary, description, acceptance criteria, priority, labels, linked issues +3. Optionally fetch comments for additional context +4. Produce a structured analysis: + +``` +Ticket: PROJ-1234 +Summary: [title] +Status: [status] +Priority: [priority] +Type: [Story/Bug/Task] + +Requirements: +1. [extracted requirement] +2. [extracted requirement] + +Acceptance Criteria: +- [ ] [criterion from ticket] + +Test Scenarios: +- Happy Path: [description] +- Error Case: [description] +- Edge Case: [description] + +Dependencies: +- [linked issues, APIs, services] + +Recommended Next Steps: +- /plan to create implementation plan +- /tdd to implement with tests first +``` + +### `/jira comment ` + +1. Summarize current session progress (what was built, tested, committed) +2. Format as a structured comment +3. Post to the Jira ticket + +### `/jira transition ` + +1. Fetch available transitions for the ticket +2. Show options to user +3. Execute the selected transition + +### `/jira search ` + +1. Execute the JQL query against Jira +2. Return a summary table of matching issues + +## Prerequisites + +This command requires Jira credentials. Choose one: + +**Option A — MCP Server (recommended):** +Add `jira` to your `mcpServers` config (see `mcp-configs/mcp-servers.json` for the template). + +**Option B — Environment variables:** +```bash +export JIRA_URL="https://yourorg.atlassian.net" +export JIRA_EMAIL="your.email@example.com" +export JIRA_API_TOKEN="your-api-token" +``` + +If credentials are missing, stop and direct the user to set them up. + +## Integration with Other Commands + +After analyzing a ticket: +- Use `/plan` to create an implementation plan from the requirements +- Use `/tdd` to implement with test-driven development +- Use `/code-review` after implementation +- Use `/jira comment` to post progress back to the ticket +- Use `/jira transition` to move the ticket when work is complete + +## Related + +- **Skill:** `skills/jira-integration/` +- **MCP config:** `mcp-configs/mcp-servers.json` → `jira` diff --git a/docs/zh-CN/AGENTS.md b/docs/zh-CN/AGENTS.md index 25336d54..3713f56c 100644 --- a/docs/zh-CN/AGENTS.md +++ b/docs/zh-CN/AGENTS.md @@ -1,6 +1,6 @@ # Everything Claude Code (ECC) — 智能体指令 -这是一个**生产就绪的 AI 编码插件**，提供 38 个专业代理、154 项技能、71 条命令以及自动化钩子工作流，用于软件开发。 +这是一个**生产就绪的 AI 编码插件**，提供 38 个专业代理、155 项技能、72 条命令以及自动化钩子工作流，用于软件开发。 **版本:** 1.9.0 @@ -147,8 +147,8 @@ ``` agents/ — 38 个专业子代理 -skills/ — 154 个工作流技能和领域知识 -commands/ — 71 个斜杠命令 +skills/ — 155 个工作流技能和领域知识 +commands/ — 72 个斜杠命令 hooks/ — 基于触发的自动化 rules/ — 始终遵循的指导方针（通用 + 每种语言） scripts/ — 跨平台 Node.js 实用工具 diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md index 28e27901..864dcbfb 100644 --- a/docs/zh-CN/README.md +++ b/docs/zh-CN/README.md @@ -209,7 +209,7 @@ npx ecc-install typescript /plugin list everything-claude-code@everything-claude-code ``` -**搞定！** 你现在可以使用 38 个智能体、154 项技能和 71 个命令了。 +**搞定！** 你现在可以使用 38 个智能体、155 项技能和 72 个命令了。 *** @@ -1095,8 +1095,8 @@ opencode | 功能特性 | Claude Code | OpenCode | 状态 | |---------|-------------|----------|--------| | 智能体 | PASS: 38 个 | PASS: 12 个 | **Claude Code 领先** | -| 命令 | PASS: 71 个 | PASS: 31 个 | **Claude Code 领先** | -| 技能 | PASS: 154 项 | PASS: 37 项 | **Claude Code 领先** | +| 命令 | PASS: 72 个 | PASS: 31 个 | **Claude Code 领先** | +| 技能 | PASS: 155 项 | PASS: 37 项 | **Claude Code 领先** | | 钩子 | PASS: 8 种事件类型 | PASS: 11 种事件 | **OpenCode 更多！** | | 规则 | PASS: 29 条 | PASS: 13 条指令 | **Claude Code 领先** | | MCP 服务器 | PASS: 14 个 | PASS: 完整 | **完全对等** | @@ -1207,8 +1207,8 @@ ECC 是**第一个最大化利用每个主要 AI 编码工具的插件**。以 | 功能特性 | Claude Code | Cursor IDE | Codex CLI | OpenCode | |---------|------------|------------|-----------|----------| | **智能体** | 38 | 共享 (AGENTS.md) | 共享 (AGENTS.md) | 12 | -| **命令** | 71 | 共享 | 基于指令 | 31 | -| **技能** | 154 | 共享 | 10 (原生格式) | 37 | +| **命令** | 72 | 共享 | 基于指令 | 31 | +| **技能** | 155 | 共享 | 10 (原生格式) | 37 | | **钩子事件** | 8 种类型 | 15 种类型 | 暂无 | 11 种类型 | | **钩子脚本** | 20+ 个脚本 | 16 个脚本 (DRY 适配器) | N/A | 插件钩子 | | **规则** | 34 (通用 + 语言) | 34 (YAML 前页) | 基于指令 | 13 条指令 | diff --git a/manifests/install-modules.json b/manifests/install-modules.json index cc688606..d2a9da22 100644 --- a/manifests/install-modules.json +++ b/manifests/install-modules.json @@ -316,6 +316,7 @@ "skills/connections-optimizer", "skills/customer-billing-ops", "skills/google-workspace-ops", + "skills/jira-integration", "skills/project-flow-ops", "skills/workspace-surface-audit" ], diff --git a/mcp-configs/mcp-servers.json b/mcp-configs/mcp-servers.json index c62d8866..e2227dab 100644 --- a/mcp-configs/mcp-servers.json +++ b/mcp-configs/mcp-servers.json @@ -1,5 +1,15 @@ { "mcpServers": { + "jira": { + "command": "uvx", + "args": ["mcp-atlassian==0.21.0"], + "env": { + "JIRA_URL": "YOUR_JIRA_URL_HERE", + "JIRA_EMAIL": "YOUR_JIRA_EMAIL_HERE", + "JIRA_API_TOKEN": "YOUR_JIRA_API_TOKEN_HERE" + }, + "description": "Jira issue tracking — search, create, update, comment, transition issues" + }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], diff --git a/skills/jira-integration/SKILL.md b/skills/jira-integration/SKILL.md new file mode 100644 index 00000000..5d32365a --- /dev/null +++ b/skills/jira-integration/SKILL.md @@ -0,0 +1,293 @@ +--- +name: jira-integration +description: Use this skill when retrieving Jira tickets, analyzing requirements, updating ticket status, adding comments, or transitioning issues. Provides Jira API patterns via MCP or direct REST calls. +origin: ECC +--- + +# Jira Integration Skill + +Retrieve, analyze, and update Jira tickets directly from your AI coding workflow. Supports both **MCP-based** (recommended) and **direct REST API** approaches. + +## When to Activate + +- Fetching a Jira ticket to understand requirements +- Extracting testable acceptance criteria from a ticket +- Adding progress comments to a Jira issue +- Transitioning a ticket status (To Do → In Progress → Done) +- Linking merge requests or branches to a Jira issue +- Searching for issues by JQL query + +## Prerequisites + +### Option A: MCP Server (Recommended) + +Install the `mcp-atlassian` MCP server. This exposes Jira tools directly to your AI agent. + +**Requirements:** +- Python 3.10+ +- `uvx` (from `uv`), installed via your package manager or the official `uv` installation documentation + +**Add to your MCP config** (e.g., `~/.claude.json` → `mcpServers`): + +```json +{ + "jira": { + "command": "uvx", + "args": ["mcp-atlassian==0.21.0"], + "env": { + "JIRA_URL": "https://YOUR_ORG.atlassian.net", + "JIRA_EMAIL": "your.email@example.com", + "JIRA_API_TOKEN": "your-api-token" + }, + "description": "Jira issue tracking — search, create, update, comment, transition" + } +} +``` + +> **Security:** Never hardcode secrets. Prefer setting `JIRA_URL`, `JIRA_EMAIL`, and `JIRA_API_TOKEN` in your system environment (or a secrets manager). Only use the MCP `env` block for local, uncommitted config files. + +**To get a Jira API token:** +1. Go to https://id.atlassian.com/manage-profile/security/api-tokens +2. Click **Create API token** +3. Copy the token — store it in your environment, never in source code + +### Option B: Direct REST API + +If MCP is not available, use the Jira REST API v3 directly via `curl` or a helper script. + +**Required environment variables:** + +| Variable | Description | +|----------|-------------| +| `JIRA_URL` | Your Jira instance URL (e.g., `https://yourorg.atlassian.net`) | +| `JIRA_EMAIL` | Your Atlassian account email | +| `JIRA_API_TOKEN` | API token from id.atlassian.com | + +Store these in your shell environment, secrets manager, or an untracked local env file. Do not commit them to the repo. + +## MCP Tools Reference + +When the `mcp-atlassian` MCP server is configured, these tools are available: + +| Tool | Purpose | Example | +|------|---------|---------| +| `jira_search` | JQL queries | `project = PROJ AND status = "In Progress"` | +| `jira_get_issue` | Fetch full issue details by key | `PROJ-1234` | +| `jira_create_issue` | Create issues (Task, Bug, Story, Epic) | New bug report | +| `jira_update_issue` | Update fields (summary, description, assignee) | Change assignee | +| `jira_transition_issue` | Change status | Move to "In Review" | +| `jira_add_comment` | Add comments | Progress update | +| `jira_get_sprint_issues` | List issues in a sprint | Active sprint review | +| `jira_create_issue_link` | Link issues (Blocks, Relates to) | Dependency tracking | +| `jira_get_issue_development_info` | See linked PRs, branches, commits | Dev context | + +> **Tip:** Always call `jira_get_transitions` before transitioning — transition IDs vary per project workflow. + +## Direct REST API Reference + +### Fetch a Ticket + +```bash +curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ + -H "Content-Type: application/json" \ + "$JIRA_URL/rest/api/3/issue/PROJ-1234" | jq '{ + key: .key, + summary: .fields.summary, + status: .fields.status.name, + priority: .fields.priority.name, + type: .fields.issuetype.name, + assignee: .fields.assignee.displayName, + labels: .fields.labels, + description: .fields.description + }' +``` + +### Fetch Comments + +```bash +curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ + -H "Content-Type: application/json" \ + "$JIRA_URL/rest/api/3/issue/PROJ-1234?fields=comment" | jq '.fields.comment.comments[] | { + author: .author.displayName, + created: .created[:10], + body: .body + }' +``` + +### Add a Comment + +```bash +curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "body": { + "version": 1, + "type": "doc", + "content": [{ + "type": "paragraph", + "content": [{"type": "text", "text": "Your comment here"}] + }] + } + }' \ + "$JIRA_URL/rest/api/3/issue/PROJ-1234/comment" +``` + +### Transition a Ticket + +```bash +# 1. Get available transitions +curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ + "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" | jq '.transitions[] | {id, name: .name}' + +# 2. Execute transition (replace TRANSITION_ID) +curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"transition": {"id": "TRANSITION_ID"}}' \ + "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" +``` + +### Search with JQL + +```bash +curl -s -G -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ + --data-urlencode "jql=project = PROJ AND status = 'In Progress'" \ + "$JIRA_URL/rest/api/3/search" +``` + +## Analyzing a Ticket + +When retrieving a ticket for development or test automation, extract: + +### 1. Testable Requirements +- **Functional requirements** — What the feature does +- **Acceptance criteria** — Conditions that must be met +- **Testable behaviors** — Specific actions and expected outcomes +- **User roles** — Who uses this feature and their permissions +- **Data requirements** — What data is needed +- **Integration points** — APIs, services, or systems involved + +### 2. Test Types Needed +- **Unit tests** — Individual functions and utilities +- **Integration tests** — API endpoints and service interactions +- **E2E tests** — User-facing UI flows +- **API tests** — Endpoint contracts and error handling + +### 3. Edge Cases & Error Scenarios +- Invalid inputs (empty, too long, special characters) +- Unauthorized access +- Network failures or timeouts +- Concurrent users or race conditions +- Boundary conditions +- Missing or null data +- State transitions (back navigation, refresh, etc.) + +### 4. Structured Analysis Output + +``` +Ticket: PROJ-1234 +Summary: [ticket title] +Status: [current status] +Priority: [High/Medium/Low] +Test Types: Unit, Integration, E2E + +Requirements: +1. [requirement 1] +2. [requirement 2] + +Acceptance Criteria: +- [ ] [criterion 1] +- [ ] [criterion 2] + +Test Scenarios: +- Happy Path: [description] +- Error Case: [description] +- Edge Case: [description] + +Test Data Needed: +- [data item 1] +- [data item 2] + +Dependencies: +- [dependency 1] +- [dependency 2] +``` + +## Updating Tickets + +### When to Update + +| Workflow Step | Jira Update | +|---|---| +| Start work | Transition to "In Progress" | +| Tests written | Comment with test coverage summary | +| Branch created | Comment with branch name | +| PR/MR created | Comment with link, link issue | +| Tests passing | Comment with results summary | +| PR/MR merged | Transition to "Done" or "In Review" | + +### Comment Templates + +**Starting Work:** +``` +Starting implementation for this ticket. +Branch: feat/PROJ-1234-feature-name +``` + +**Tests Implemented:** +``` +Automated tests implemented: + +Unit Tests: +- [test file 1] — [what it covers] +- [test file 2] — [what it covers] + +Integration Tests: +- [test file] — [endpoints/flows covered] + +All tests passing locally. Coverage: XX% +``` + +**PR Created:** +``` +Pull request created: +[PR Title](https://github.com/org/repo/pull/XXX) + +Ready for review. +``` + +**Work Complete:** +``` +Implementation complete. + +PR merged: [link] +Test results: All passing (X/Y) +Coverage: XX% +``` + +## Security Guidelines + +- **Never hardcode** Jira API tokens in source code or skill files +- **Always use** environment variables or a secrets manager +- **Add `.env`** to `.gitignore` in every project +- **Rotate tokens** immediately if exposed in git history +- **Use least-privilege** API tokens scoped to required projects +- **Validate** that credentials are set before making API calls — fail fast with a clear message + +## Troubleshooting + +| Error | Cause | Fix | +|---|---|---| +| `401 Unauthorized` | Invalid or expired API token | Regenerate at id.atlassian.com | +| `403 Forbidden` | Token lacks project permissions | Check token scopes and project access | +| `404 Not Found` | Wrong ticket key or base URL | Verify `JIRA_URL` and ticket key | +| `spawn uvx ENOENT` | IDE cannot find `uvx` on PATH | Use full path (e.g., `~/.local/bin/uvx`) or set PATH in `~/.zprofile` | +| Connection timeout | Network/VPN issue | Check VPN connection and firewall rules | + +## Best Practices + +- Update Jira as you go, not all at once at the end +- Keep comments concise but informative +- Link rather than copy — point to PRs, test reports, and dashboards +- Use @mentions if you need input from others +- Check linked issues to understand full feature scope before starting +- If acceptance criteria are vague, ask for clarification before writing code