feat: add jira integration workflow

2026-04-03 15:43:31 +08:00 · 2026-04-02 17:51:03 -07:00
parent badccc3db9
commit be0c56957b
10 changed files with 429 additions and 17 deletions
--- 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
--- 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 |
--- 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-* 命令需要额外配置

--- 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.
--- a/commands/jira.md
+++ 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 <TICKET-KEY>          # Fetch and analyze a ticket
+/jira comment <TICKET-KEY>      # Add a progress comment
+/jira transition <TICKET-KEY>   # Change ticket status
+/jira search <JQL>              # 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 <TICKET-KEY>`
+
+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 <TICKET-KEY>`
+
+1. Summarize current session progress (what was built, tested, committed)
+2. Format as a structured comment
+3. Post to the Jira ticket
+
+### `/jira transition <TICKET-KEY>`
+
+1. Fetch available transitions for the ticket
+2. Show options to user
+3. Execute the selected transition
+
+### `/jira search <JQL>`
+
+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`
--- 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 实用工具
--- 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 条指令 |
--- 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"
      ],
--- 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"],
--- a/skills/jira-integration/SKILL.md
+++ 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