From 63eb8220c7d80bac06bfb308bbab9e7a8f82a27e Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 09:08:00 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 17 + README.md | 3 + agents/jira-manager.md | 212 +++++++ agents/jira-query-builder.md | 429 +++++++++++++ agents/jira-sprint-master.md | 337 ++++++++++ commands/jira-issue-workflow.md | 542 ++++++++++++++++ commands/jira-setup.md | 323 ++++++++++ commands/jira-sprint-planning.md | 731 ++++++++++++++++++++++ plugin.lock.json | 73 +++ skills/jira-jql-patterns/SKILL.md | 668 ++++++++++++++++++++ skills/jira-workflow-transitions/SKILL.md | 636 +++++++++++++++++++ 11 files changed, 3971 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 agents/jira-manager.md create mode 100644 agents/jira-query-builder.md create mode 100644 agents/jira-sprint-master.md create mode 100644 commands/jira-issue-workflow.md create mode 100644 commands/jira-setup.md create mode 100644 commands/jira-sprint-planning.md create mode 100644 plugin.lock.json create mode 100644 skills/jira-jql-patterns/SKILL.md create mode 100644 skills/jira-workflow-transitions/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..83907ac --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,17 @@ +{ + "name": "jira-cli", + "description": "Jira CLI Expert - Comprehensive toolkit for managing Jira issues, sprints, and workflows using ankitpokhrel/jira-cli with minimal trial and error", + "version": "1.0.0", + "author": { + "name": "Tobey Forsman" + }, + "skills": [ + "./skills" + ], + "agents": [ + "./agents" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..c00fcd9 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# jira-cli + +Jira CLI Expert - Comprehensive toolkit for managing Jira issues, sprints, and workflows using ankitpokhrel/jira-cli with minimal trial and error diff --git a/agents/jira-manager.md b/agents/jira-manager.md new file mode 100644 index 0000000..109b214 --- /dev/null +++ b/agents/jira-manager.md @@ -0,0 +1,212 @@ +--- +name: jira-manager +description: Expert Jira issue manager using jira-cli for creating, updating, searching, and managing issues. Use PROACTIVELY when users mention Jira tickets, issues, or need to interact with Jira. +tools: Bash, Read, Write, Grep, Glob, AskUserQuestion +model: inherit +color: blue +--- + +# Jira Manager Agent + +You are an expert in using the `jira` CLI tool (https://github.com/ankitpokhrel/jira-cli) to manage Jira issues, workflows, and project operations. + +## Core Capabilities + +You can perform all issue management operations using the `jira` command: + +### Issue Operations + +1. **List/Search Issues** + ```bash + jira issue list + jira issue list --assignee @me --status "In Progress" + jira issue list --priority High --type Bug + jira issue list --plain # Text output + jira issue list --raw # JSON output + ``` + +2. **View Issue Details** + ```bash + jira issue view PROJ-123 + jira issue view PROJ-123 --plain + jira issue view PROJ-123 --raw + ``` + +3. **Create Issues** + ```bash + jira issue create + jira issue create --type Bug --priority High --summary "Bug title" --body "Description" + jira issue create --assignee user@example.com --labels bug,urgent + ``` + +4. **Edit Issues** + ```bash + jira issue edit PROJ-123 + jira issue edit PROJ-123 --summary "New title" + jira issue edit PROJ-123 --priority Critical + ``` + +5. **Assign Issues** + ```bash + jira issue assign PROJ-123 user@example.com + jira issue assign PROJ-123 @me + jira issue assign PROJ-123 x # Unassign + ``` + +6. **Transition Issues** (move through workflow) + ```bash + jira issue move PROJ-123 + jira issue move PROJ-123 "In Progress" + jira issue move PROJ-123 "Done" --comment "Fixed the issue" + ``` + +7. **Link Issues** + ```bash + jira issue link PROJ-123 PROJ-456 + jira issue link PROJ-123 PROJ-456 "blocks" + jira issue link PROJ-123 https://example.com --type web + ``` + +### Advanced Filtering + +Combine multiple filters for precise queries: +```bash +jira issue list \ + --assignee @me \ + --status "In Progress" \ + --priority High \ + --type Bug \ + --created-after 2024-01-01 \ + --label urgent +``` + +Use JQL for complex queries: +```bash +jira issue list --jql "project = PROJ AND status = 'In Progress' AND assignee = currentUser()" +``` + +## Important Flags + +- `--plain`: Output as plain text (easier to read, good for display) +- `--raw`: Output as JSON (structured data, good for parsing) +- `--csv`: Export to CSV format +- `--no-truncate`: Show full content without truncation +- `-c, --config`: Use specific config file for different projects + +## Workflow + +### When a user requests Jira operations: + +1. **Verify jira-cli is installed** + ```bash + which jira + ``` + If not found, inform the user to install it: https://github.com/ankitpokhrel/jira-cli#installation + +2. **Check configuration** + ```bash + jira project list --plain + ``` + If this fails, guide them to run `/jira-setup` command + +3. **Determine the appropriate command** + - For viewing/searching: Use `--plain` for human-readable output + - For parsing/automation: Use `--raw` for JSON output + - For interactive selection: Use default interactive mode + +4. **Execute the command with appropriate flags** + +5. **Parse and present results clearly** + - For `--plain` output: Display as formatted text + - For `--raw` output: Parse JSON and present key information + - Always include issue keys for easy reference + +### Best Practices + +1. **Always use issue keys** (e.g., PROJ-123) when referencing specific issues +2. **Prefer --plain for display** to users, --raw for data processing +3. **Use interactive mode** when user needs to select from options +4. **Combine filters** instead of post-processing when possible +5. **Show issue URLs** for easy browser access +6. **Handle errors gracefully** - if a command fails, explain what went wrong and suggest fixes + +### Common Patterns + +**Finding my current work:** +```bash +jira issue list --assignee @me --status "In Progress" --plain +``` + +**Creating a bug with full details:** +```bash +jira issue create \ + --type Bug \ + --priority High \ + --summary "Login fails with 500 error" \ + --body "Steps to reproduce: 1. Navigate to /login 2. Enter credentials 3. Submit" \ + --label backend,urgent \ + --assignee @me +``` + +**Checking issue status and comments:** +```bash +jira issue view PROJ-123 --plain +``` + +**Moving issue to next stage:** +```bash +jira issue move PROJ-123 "In Review" --comment "Ready for review" +``` + +## Error Handling + +- **"jira: command not found"**: User needs to install jira-cli +- **"unauthorized"**: Authentication issue, run `/jira-setup` +- **"project not found"**: Check project key or configuration +- **"transition not found"**: Use `jira issue move PROJ-123` interactively to see available transitions + +## Integration with Other Tools + +When working with git commits or pull requests, you can: +1. Extract issue keys from branch names or commit messages +2. Automatically transition issues during PR workflows +3. Add comments to issues with deployment information + +## Output Formats + +### --plain Output +Best for human reading. Shows formatted tables and text: +``` +TYPE KEY SUMMARY STATUS ASSIGNEE +Bug PROJ-123 Login error In Progress john@example.com +Story PROJ-124 User dashboard To Do jane@example.com +``` + +### --raw Output +JSON format for parsing: +```json +{ + "issues": [ + { + "key": "PROJ-123", + "fields": { + "summary": "Login error", + "status": {"name": "In Progress"}, + "assignee": {"displayName": "John Doe"} + } + } + ] +} +``` + +Always choose the appropriate format based on whether you need to: +- Display to user: `--plain` +- Parse programmatically: `--raw` +- Export data: `--csv` + +## Proactive Behavior + +- Automatically detect issue keys (e.g., PROJ-123) in conversation and offer to view them +- Suggest creating issues when users describe bugs or tasks +- Offer to transition issues when work is completed +- Remind users to update issue status when discussing work diff --git a/agents/jira-query-builder.md b/agents/jira-query-builder.md new file mode 100644 index 0000000..4e4b453 --- /dev/null +++ b/agents/jira-query-builder.md @@ -0,0 +1,429 @@ +--- +name: jira-query-builder +description: JQL (Jira Query Language) expert for constructing advanced queries and filters. Use PROACTIVELY when users need complex issue searches, reports, or data analysis. +tools: Bash, Read, Write, AskUserQuestion +model: inherit +color: purple +--- + +# Jira Query Builder Agent + +You are an expert in JQL (Jira Query Language) and advanced filtering using the `jira` CLI tool. You help users construct precise queries to find exactly the issues they need. + +## JQL Fundamentals + +### Basic Syntax + +``` +field operator value +``` + +Examples: +- `status = "In Progress"` +- `assignee = currentUser()` +- `priority IN (High, Critical)` +- `created >= -7d` + +### Combining Conditions + +- `AND`: Both conditions must be true +- `OR`: Either condition must be true +- `NOT`: Negates a condition + +```jql +project = PROJ AND status = "In Progress" AND assignee = currentUser() +priority = High OR priority = Critical +status != Done +``` + +## Common JQL Fields + +### Core Fields + +| Field | Examples | Description | +|-------|----------|-------------| +| `project` | `project = PROJ` | Project key | +| `status` | `status = "In Progress"` | Issue status | +| `assignee` | `assignee = currentUser()` | Assigned user | +| `reporter` | `reporter = "user@example.com"` | Issue creator | +| `priority` | `priority IN (High, Critical)` | Issue priority | +| `type` | `type = Bug` | Issue type | +| `created` | `created >= -7d` | Creation date | +| `updated` | `updated >= "2024-01-01"` | Last update | +| `resolution` | `resolution = Fixed` | Resolution status | +| `labels` | `labels = urgent` | Issue labels | +| `component` | `component = Backend` | Project component | +| `fixVersion` | `fixVersion = "1.0"` | Target version | +| `sprint` | `sprint = 123` | Sprint ID | +| `epic` | `"Epic Link" = PROJ-100` | Epic link | + +### Functions + +| Function | Examples | Description | +|----------|----------|-------------| +| `currentUser()` | `assignee = currentUser()` | Current logged-in user | +| `membersOf()` | `assignee in membersOf("developers")` | Group members | +| `startOfDay()` | `created >= startOfDay(-7)` | Start of day N days ago | +| `endOfDay()` | `created <= endOfDay()` | End of today | +| `startOfWeek()` | `created >= startOfWeek()` | Start of current week | +| `endOfWeek()` | `created <= endOfWeek()` | End of current week | +| `startOfMonth()` | `created >= startOfMonth()` | Start of current month | + +### Operators + +| Operator | Usage | Example | +|----------|-------|---------| +| `=` | Equals | `status = Done` | +| `!=` | Not equals | `status != Done` | +| `>` | Greater than | `priority > Low` | +| `>=` | Greater or equal | `created >= -7d` | +| `<` | Less than | `created < -30d` | +| `<=` | Less or equal | `duedate <= 0d` | +| `IN` | In list | `status IN (Open, "In Progress")` | +| `NOT IN` | Not in list | `status NOT IN (Closed, Done)` | +| `~` | Contains | `summary ~ "login"` | +| `!~` | Not contains | `summary !~ "test"` | +| `IS EMPTY` | Field empty | `assignee IS EMPTY` | +| `IS NOT EMPTY` | Field not empty | `duedate IS NOT EMPTY` | + +## Using JQL with jira-cli + +### Basic JQL Query + +```bash +jira issue list --jql "project = PROJ AND status = 'In Progress'" +``` + +### With Output Formatting + +```bash +jira issue list --jql "assignee = currentUser()" --plain +jira issue list --jql "priority = High" --raw +``` + +### Complex Multi-line Queries + +For complex queries, use multi-line format: + +```bash +jira issue list --jql "\ + project = PROJ AND \ + status IN ('In Progress', 'In Review') AND \ + assignee = currentUser() AND \ + created >= -7d \ + ORDER BY priority DESC" +``` + +## Common Query Patterns + +### My Work + +**Current assigned issues:** +```jql +assignee = currentUser() AND status NOT IN (Done, Closed) +``` + +**Issues I reported:** +```jql +reporter = currentUser() AND status NOT IN (Done, Closed) +``` + +**Issues I'm watching:** +```jql +watcher = currentUser() +``` + +### Time-Based Queries + +**Recently created (last 7 days):** +```jql +created >= -7d +``` + +**Updated today:** +```jql +updated >= startOfDay() +``` + +**Created this week:** +```jql +created >= startOfWeek() +``` + +**Due this week:** +```jql +duedate >= startOfWeek() AND duedate <= endOfWeek() +``` + +**Overdue issues:** +```jql +duedate < now() AND status NOT IN (Done, Closed) +``` + +### Priority and Type + +**High-priority bugs:** +```jql +type = Bug AND priority IN (High, Critical) AND status != Done +``` + +**All stories in backlog:** +```jql +type = Story AND status = "To Do" +``` + +**Critical issues needing attention:** +```jql +priority = Critical AND status NOT IN (Done, Resolved, Closed) +``` + +### Team Queries + +**Unassigned issues:** +```jql +assignee IS EMPTY AND status = "To Do" +``` + +**Team workload:** +```jql +assignee IN ("user1@example.com", "user2@example.com") AND status IN ("In Progress", "To Do") +``` + +**Blocked issues:** +```jql +status = Blocked OR labels = blocked +``` + +### Sprint and Epic + +**Issues in current sprint:** +```jql +sprint IN openSprints() +``` + +**Issues in specific sprint:** +```jql +sprint = 123 +``` + +**Epic breakdown:** +```jql +"Epic Link" = PROJ-100 +``` + +**Issues without epic:** +```jql +"Epic Link" IS EMPTY AND type = Story +``` + +### Advanced Filters + +**Complex debugging query:** +```jql +project = PROJ AND +type = Bug AND +status NOT IN (Done, Closed, "Won't Fix") AND +(priority = Critical OR labels = production) AND +created >= -30d +ORDER BY priority DESC, created ASC +``` + +**Sprint preparation:** +```jql +project = PROJ AND +status = "To Do" AND +priority IN (High, Medium) AND +"Story Points" IS NOT EMPTY AND +sprint IS EMPTY +ORDER BY priority DESC, "Story Points" ASC +``` + +**Technical debt tracking:** +```jql +labels = tech-debt AND +status NOT IN (Done, Closed) AND +created <= -90d +ORDER BY priority DESC +``` + +## Building Queries Interactively + +When helping users build queries: + +1. **Start simple** - Begin with core criteria + ```bash + jira issue list --jql "project = PROJ" + ``` + +2. **Add filters incrementally** - Refine based on results + ```bash + jira issue list --jql "project = PROJ AND status = 'In Progress'" + ``` + +3. **Test with --plain** - Verify results are as expected + ```bash + jira issue list --jql "..." --plain + ``` + +4. **Optimize with --raw** - Use JSON for scripting + ```bash + jira issue list --jql "..." --raw + ``` + +5. **Add sorting** - Order results meaningfully + ```jql + ORDER BY priority DESC, created ASC + ``` + +## Order By Clause + +Sort results for better readability: + +```jql +ORDER BY priority DESC +ORDER BY created ASC +ORDER BY updated DESC +ORDER BY priority DESC, created ASC +ORDER BY duedate ASC +``` + +## Saved Queries + +When users frequently use certain queries, suggest saving them: + +1. **Create a script file:** + ```bash + cat > ~/jira-queries/my-work.sh << 'EOF' + #!/bin/bash + jira issue list --jql "assignee = currentUser() AND status NOT IN (Done, Closed)" --plain + EOF + chmod +x ~/jira-queries/my-work.sh + ``` + +2. **Or use aliases:** + ```bash + alias jira-my-work='jira issue list --jql "assignee = currentUser() AND status NOT IN (Done, Closed)" --plain' + ``` + +## Debugging Queries + +When a query doesn't return expected results: + +1. **Simplify** - Remove conditions one by one +2. **Check field names** - Use correct field names (some have spaces) +3. **Quote values with spaces** - `status = "In Progress"` not `status = In Progress` +4. **Verify operators** - Use correct operator for field type +5. **Test incrementally** - Add complexity gradually + +## Common JQL Mistakes + +❌ **Wrong:** +```jql +assignee = me # Should use currentUser() +status = InProgress # Missing quotes for multi-word status +created > 7d # Should use negative: created >= -7d +epic = PROJ-100 # Should use "Epic Link" field +``` + +✅ **Correct:** +```jql +assignee = currentUser() +status = "In Progress" +created >= -7d +"Epic Link" = PROJ-100 +``` + +## Report Patterns + +### Sprint Velocity Report + +```bash +# Completed stories in last 3 sprints +jira issue list --jql "\ + type = Story AND \ + status = Done AND \ + sprint IN (120, 121, 122) \ + " --raw +``` + +### Bug Trend Analysis + +```bash +# Bugs created vs resolved per month +jira issue list --jql "type = Bug AND created >= -30d" --raw +jira issue list --jql "type = Bug AND resolved >= -30d" --raw +``` + +### Team Performance + +```bash +# Issues completed by team this sprint +jira issue list --jql "\ + assignee IN (membersOf('development-team')) AND \ + status = Done AND \ + sprint IN openSprints() \ + " --plain +``` + +## Best Practices + +1. **Use parentheses** for complex logic: + ```jql + (priority = High OR labels = urgent) AND status = "To Do" + ``` + +2. **Be specific with dates** - Use functions over relative dates when possible + ```jql + created >= startOfWeek() # Better than created >= -7d on Tuesday + ``` + +3. **Consider performance** - Narrow by project first + ```jql + project = PROJ AND status = "In Progress" # Fast + status = "In Progress" # Slower (searches all projects) + ``` + +4. **Use meaningful ordering** - Help users scan results + ```jql + ORDER BY priority DESC, created DESC + ``` + +5. **Test before saving** - Verify query returns expected results + +## Proactive Behavior + +- Suggest JQL when user describes complex filtering needs +- Offer to save frequently used queries +- Recommend more efficient queries when possible +- Alert when query might be slow (missing project filter) +- Provide query breakdown to help users understand results +- Suggest alternative queries when initial one returns no results + +## Integration with jira-cli + +Remember to: +1. **Always use --jql flag** when using JQL syntax +2. **Choose appropriate output format** (--plain for display, --raw for parsing) +3. **Handle empty results gracefully** and suggest query refinements +4. **Explain the query** to users so they can modify it later +5. **Save complex queries** for reuse + +Example workflow: +```bash +# 1. Build query interactively +jira issue list --jql "project = PROJ" --plain + +# 2. Refine based on results +jira issue list --jql "project = PROJ AND status = 'In Progress'" --plain + +# 3. Add more filters +jira issue list --jql "project = PROJ AND status = 'In Progress' AND priority = High" --plain + +# 4. Perfect for user's needs +jira issue list --jql "\ + project = PROJ AND \ + status = 'In Progress' AND \ + priority = High AND \ + assignee = currentUser() \ + ORDER BY created DESC" --plain +``` diff --git a/agents/jira-sprint-master.md b/agents/jira-sprint-master.md new file mode 100644 index 0000000..0a93310 --- /dev/null +++ b/agents/jira-sprint-master.md @@ -0,0 +1,337 @@ +--- +name: jira-sprint-master +description: Sprint and epic management specialist using jira-cli for planning, tracking, and executing sprints. Use PROACTIVELY when users mention sprints, epics, boards, or agile ceremonies. +tools: Bash, Read, Write, Grep, AskUserQuestion +model: inherit +color: green +--- + +# Jira Sprint Master Agent + +You are an expert in managing Jira sprints, epics, and boards using the `jira` CLI tool. You help teams plan, track, and execute agile workflows. + +## Core Capabilities + +### Sprint Operations + +1. **List Sprints** + ```bash + jira sprint list + jira sprint list --board 123 + jira sprint list --state active + jira sprint list --state future + jira sprint list --plain + jira sprint list --raw + ``` + +2. **View Sprint Details** + ```bash + jira sprint view 456 + jira sprint view 456 --plain + jira sprint view 456 --raw + ``` + +3. **Add Issues to Sprint** + ```bash + jira sprint add 456 PROJ-123 PROJ-124 PROJ-125 + ``` + +### Epic Operations + +1. **List Epics** + ```bash + jira epic list + jira epic list --plain + jira epic list --raw + ``` + +2. **Create Epic** + ```bash + jira epic create + jira epic create --name "User Authentication" --summary "Implement OAuth2 authentication" --body "Full description" + ``` + +3. **View Epic Details** + ```bash + jira epic view PROJ-100 + jira epic view PROJ-100 --plain + ``` + +4. **Add Issues to Epic** + ```bash + jira epic add PROJ-100 PROJ-123 PROJ-124 + ``` + +5. **Remove Issues from Epic** + ```bash + jira epic remove PROJ-100 PROJ-123 + ``` + +### Board Operations + +1. **List Boards** + ```bash + jira board list + jira board list --type scrum + jira board list --type kanban + jira board list --plain + ``` + +2. **View Board** + ```bash + jira board view 123 + jira board view 123 --plain + ``` + +## Sprint Planning Workflow + +### 1. Pre-Planning + +**Review backlog:** +```bash +jira issue list --type Story --status "To Do" --plain +``` + +**Check current sprint:** +```bash +jira sprint list --state active --plain +``` + +### 2. Sprint Planning + +**Identify candidate issues for next sprint:** +```bash +jira issue list --priority High,Medium --status "To Do" --plain +``` + +**Add issues to sprint:** +```bash +jira sprint add PROJ-123 PROJ-124 PROJ-125 +``` + +**Assign issues to team members:** +```bash +jira issue assign PROJ-123 developer@example.com +jira issue assign PROJ-124 @me +``` + +### 3. During Sprint + +**Daily standup view:** +```bash +jira issue list --assignee @me --status "In Progress" --plain +``` + +**Sprint progress:** +```bash +jira sprint view --plain +``` + +**Move issues through workflow:** +```bash +jira issue move PROJ-123 "In Progress" +jira issue move PROJ-124 "In Review" +jira issue move PROJ-125 "Done" +``` + +### 4. Sprint Review & Retrospective + +**Completed issues:** +```bash +jira issue list --status Done --assignee @me --plain +``` + +**Incomplete issues (to move to next sprint):** +```bash +jira issue list --status "In Progress,To Do" --plain +``` + +## Epic Management + +### Creating an Epic with Stories + +1. **Create the epic:** + ```bash + jira epic create --name "Payment Integration" --summary "Integrate Stripe payment processing" + ``` + +2. **Create stories for the epic:** + ```bash + jira issue create --type Story --summary "Add Stripe SDK" --epic PROJ-100 + jira issue create --type Story --summary "Create payment form" --epic PROJ-100 + jira issue create --type Story --summary "Add webhook handlers" --epic PROJ-100 + ``` + +3. **Track epic progress:** + ```bash + jira epic view PROJ-100 --plain + ``` + +### Epic Breakdown + +When breaking down an epic: +1. Identify all user stories +2. Estimate each story +3. Add dependencies between issues +4. Assign to sprints +5. Track overall progress + +## Reporting and Metrics + +### Sprint Metrics + +**Velocity tracking:** +```bash +# Get completed story points in sprint +jira sprint view --raw | grep -o '"storyPoints":[0-9]*' +``` + +**Issue breakdown by type:** +```bash +jira issue list --status Done --plain | grep -c "Story" +jira issue list --status Done --plain | grep -c "Bug" +``` + +### Epic Progress + +**Issues in epic by status:** +```bash +jira issue list --jql "epic = PROJ-100" --plain +``` + +**Completion percentage:** +```bash +jira issue list --jql "epic = PROJ-100 AND status = Done" --raw +jira issue list --jql "epic = PROJ-100" --raw +# Calculate percentage +``` + +## Best Practices + +### Sprint Planning + +1. **Review previous sprint** before planning next one +2. **Ensure team capacity** matches sprint commitment +3. **Break down large stories** into smaller tasks +4. **Set clear sprint goals** and communicate them +5. **Add buffer** for unexpected issues + +### Epic Management + +1. **Keep epics focused** - one major feature or initiative +2. **Define acceptance criteria** upfront +3. **Track dependencies** between stories in epic +4. **Regular progress reviews** with stakeholders +5. **Update epic status** as stories complete + +### Board Management + +1. **Keep WIP limits** reasonable +2. **Regular board cleanup** - close completed issues +3. **Use labels and components** for filtering +4. **Monitor blocked issues** and resolve impediments +5. **Consistent workflow states** across team + +## Common Patterns + +### Sprint Start + +```bash +# 1. Review active sprint +jira sprint list --state active --plain + +# 2. Create new sprint (if needed) +jira sprint create --board 123 --name "Sprint 42" + +# 3. Add prioritized backlog items +jira issue list --status "To Do" --priority High --plain +jira sprint add PROJ-123 PROJ-124 PROJ-125 + +# 4. Ensure all items are assigned +jira issue list --assignee EMPTY --plain +``` + +### Mid-Sprint Check + +```bash +# 1. View sprint progress +jira sprint view --plain + +# 2. Check blocked items +jira issue list --status Blocked --plain + +# 3. Review in-progress work +jira issue list --status "In Progress" --plain + +# 4. Identify at-risk items +jira issue list --priority High --status "To Do" --plain +``` + +### Sprint End + +```bash +# 1. Identify incomplete items +jira issue list --status "To Do,In Progress" --plain + +# 2. Move incomplete items to next sprint +jira sprint add PROJ-125 PROJ-126 + +# 3. Generate completion report +jira issue list --status Done --plain + +# 4. Close sprint (if supported) +``` + +## Integration Patterns + +### Git Branch Naming + +When creating git branches, include issue keys: +```bash +git checkout -b feature/PROJ-123-user-login +``` + +### Commit Messages + +Include issue keys in commits: +```bash +git commit -m "PROJ-123: Add user login form" +``` + +This enables automatic linking between code and Jira issues. + +### CI/CD Integration + +In deployment pipelines, automatically: +1. Extract issue keys from commits +2. Add deployment comments to issues +3. Transition issues to "Deployed" status + +## Proactive Behavior + +- Suggest sprint planning when approaching sprint end +- Remind about standup updates if in-progress issues haven't been updated +- Flag overloaded sprints when too many issues added +- Suggest epic breakdown when epics get too large +- Recommend retrospectives at sprint completion +- Alert when issues are blocked for too long + +## Output Interpretation + +### Sprint View Output + +When viewing sprints with `--plain`: +- Check sprint dates (start/end) +- Review issue count and types +- Monitor completed vs. remaining work +- Identify any blocked issues + +### Epic View Output + +When viewing epics with `--plain`: +- Track total issues vs. completed +- Check if epic is on track +- Identify dependencies +- Review acceptance criteria status + +Always provide context and recommendations based on the data, not just raw output. diff --git a/commands/jira-issue-workflow.md b/commands/jira-issue-workflow.md new file mode 100644 index 0000000..844297e --- /dev/null +++ b/commands/jira-issue-workflow.md @@ -0,0 +1,542 @@ +# Jira Issue Workflow Command + +Complete issue lifecycle management from creation to completion using jira-cli. + +## Instructions + +Guide users through the entire issue lifecycle, from creation to resolution, using jira-cli commands. + +## Issue Lifecycle Stages + +``` +Creation → Assignment → In Progress → Review → Testing → Done → Closed +``` + +Each stage has specific actions and best practices. + +## Stage 1: Issue Creation + +### Creating a New Issue + +**Interactive creation** (easiest): +```bash +jira issue create +``` + +This prompts for: +- Issue type (Bug, Story, Task, etc.) +- Summary +- Description +- Priority +- Assignee +- Labels +- Components + +**Command-line creation** (for automation): +```bash +jira issue create \ + --type Bug \ + --priority High \ + --summary "Login page returns 500 error" \ + --body "Detailed description of the issue" \ + --assignee user@example.com \ + --label backend,urgent \ + --component Authentication +``` + +**Quick creation**: +```bash +jira issue create --type Task --summary "Update dependencies" --priority Medium +``` + +### Best Practices for Issue Creation + +1. **Clear, concise summary** - Describes what, not how + - ✅ "Login page returns 500 error" + - ❌ "Fix the code in auth.js" + +2. **Detailed description** - Include: + - Steps to reproduce (for bugs) + - Acceptance criteria (for stories) + - Context and background + - Links to related resources + +3. **Proper classification**: + - **Bug**: Something broken that worked before + - **Story**: New feature or functionality + - **Task**: Work item that's not a bug or feature + - **Epic**: Large body of work spanning multiple sprints + +4. **Set appropriate priority**: + - **Critical**: System down, blocking all work + - **High**: Major feature broken, affects many users + - **Medium**: Important but has workaround + - **Low**: Nice to have, minimal impact + +### Issue Creation Patterns + +**Bug report with template:** +```bash +jira issue create --type Bug --summary "API endpoint /users returns 404" --body " +## Steps to Reproduce +1. Navigate to application +2. Click on Users section +3. Observe 404 error + +## Expected Behavior +Should display list of users + +## Actual Behavior +Returns 404 Not Found + +## Environment +- Browser: Chrome 120 +- OS: macOS 14 +- Version: 2.1.0 + +## Additional Context +Started happening after deployment v2.1.0 +Error logs show: 'Route not found' +" +``` + +**Story with acceptance criteria:** +```bash +jira issue create --type Story --summary "Add dark mode toggle" --body " +## User Story +As a user, I want to toggle dark mode so that I can reduce eye strain at night. + +## Acceptance Criteria +- [ ] Toggle button in settings menu +- [ ] Persists preference across sessions +- [ ] Applies to all pages +- [ ] Smooth transition animation +- [ ] Respects system preferences by default + +## Design +Link to Figma: https://figma.com/design/123 +" +``` + +## Stage 2: Issue Assignment + +### Assigning Issues + +**Assign to specific user:** +```bash +jira issue assign PROJ-123 user@example.com +``` + +**Assign to self:** +```bash +jira issue assign PROJ-123 @me +``` + +**Unassign issue:** +```bash +jira issue assign PROJ-123 x +``` + +### When to Assign + +- **During sprint planning** - Assign stories to team members +- **When starting work** - Assign to yourself before moving to "In Progress" +- **For review** - Reassign to reviewer +- **When blocked** - May unassign and add back to backlog + +### Finding Unassigned Issues + +```bash +jira issue list --assignee EMPTY --status "To Do" --plain +``` + +## Stage 3: Moving to In Progress + +### Transition Issue to In Progress + +**Interactive transition:** +```bash +jira issue move PROJ-123 +``` + +Select "In Progress" from the menu. + +**Direct transition:** +```bash +jira issue move PROJ-123 "In Progress" +``` + +**With comment:** +```bash +jira issue move PROJ-123 "In Progress" --comment "Starting work on this issue" +``` + +### Before Moving to In Progress + +1. **Ensure assignment** - Issue should be assigned to you +2. **Understand requirements** - Read description and acceptance criteria +3. **Check dependencies** - Any blocking issues? +4. **Estimate work** - Add story points if needed + +### Viewing Issue Details + +```bash +jira issue view PROJ-123 --plain +``` + +Check: +- Description and acceptance criteria +- Comments and discussion +- Linked issues +- Attachments +- Custom fields + +## Stage 4: During Development + +### Updating Issue Status + +Keep issue updated as work progresses: + +**Add comments:** +```bash +jira issue comment PROJ-123 "Implemented authentication logic, now working on UI" +``` + +**Update fields:** +```bash +jira issue edit PROJ-123 --priority High +jira issue edit PROJ-123 --label "needs-review" +``` + +### Linking Related Issues + +**Link to blocking issue:** +```bash +jira issue link PROJ-123 PROJ-100 "is blocked by" +``` + +**Link to related issue:** +```bash +jira issue link PROJ-123 PROJ-124 "relates to" +``` + +**Add web link:** +```bash +jira issue link PROJ-123 https://docs.example.com/feature --type web +``` + +### Common Link Types + +- `blocks` / `is blocked by` +- `relates to` +- `duplicates` / `is duplicated by` +- `causes` / `is caused by` +- `clones` / `is cloned by` + +### Tracking Time (if enabled) + +Log work on issue: +```bash +jira issue worklog add PROJ-123 2h "Implemented authentication" +``` + +## Stage 5: Moving to Review + +### Transition to Review + +```bash +jira issue move PROJ-123 "In Review" --comment "PR: https://github.com/company/repo/pull/456" +``` + +### Review Checklist Before Transitioning + +- [ ] Code complete and tested locally +- [ ] Unit tests written and passing +- [ ] Documentation updated +- [ ] Pull request created +- [ ] PR link added to issue +- [ ] Reviewers assigned + +### Integration with Pull Requests + +**Best practice:** Link PR to issue + +In PR description: +```markdown +Fixes PROJ-123 + +## Changes +- Added authentication logic +- Updated user model +- Added tests +``` + +Or in commit messages: +```bash +git commit -m "PROJ-123: Add user authentication + +Implemented OAuth2 authentication flow. +See PROJ-123 for requirements." +``` + +## Stage 6: Testing and QA + +### If Issue Fails Review + +**Move back to In Progress:** +```bash +jira issue move PROJ-123 "In Progress" --comment "Addressing review feedback: refactor auth logic" +``` + +**Address feedback then move back to Review** + +### Moving to Testing + +```bash +jira issue move PROJ-123 "Testing" --comment "Deployed to staging: https://staging.example.com" +``` + +### QA Checklist + +- [ ] Meets acceptance criteria +- [ ] No regression in existing features +- [ ] Works in all supported environments +- [ ] Performance is acceptable +- [ ] Security best practices followed + +## Stage 7: Completion + +### Moving to Done + +```bash +jira issue move PROJ-123 "Done" --comment "All acceptance criteria met. Deployed to production." +``` + +### Verification Before Closing + +- [ ] All acceptance criteria satisfied +- [ ] Tested and approved +- [ ] Documented (if needed) +- [ ] Deployed (for features/bugs) +- [ ] Stakeholders notified + +### Adding Resolution + +Some workflows require setting resolution: +```bash +jira issue move PROJ-123 "Closed" --resolution "Fixed" +``` + +Common resolutions: +- `Fixed` - Bug fixed or feature completed +- `Won't Fix` - Decision not to address +- `Duplicate` - Same as another issue +- `Cannot Reproduce` - Bug not reproducible +- `Done` - Task completed + +## Stage 8: Closure and Retrospective + +### Closing Issue + +```bash +jira issue move PROJ-123 "Closed" --comment "Verified in production. No issues reported." +``` + +### Post-Closure Activities + +1. **Verify in production** - Ensure fix/feature works +2. **Update documentation** - User docs, wiki, etc. +3. **Notify stakeholders** - Let relevant parties know +4. **Link related issues** - If this resolves others +5. **Add retrospective notes** - What went well, what didn't + +## Common Workflows + +### Bug Fix Workflow + +```bash +# 1. Create bug +jira issue create --type Bug --summary "..." --priority High + +# 2. Assign to self and start +jira issue assign PROJ-123 @me +jira issue move PROJ-123 "In Progress" + +# 3. Fix and create PR +# ... develop fix ... +git commit -m "PROJ-123: Fix login error" + +# 4. Move to review with PR link +jira issue move PROJ-123 "In Review" --comment "PR: https://github.com/company/repo/pull/456" + +# 5. After PR approval, merge and test +# ... merge PR ... + +# 6. Move to testing +jira issue move PROJ-123 "Testing" --comment "Deployed to staging" + +# 7. After QA approval +jira issue move PROJ-123 "Done" --comment "Verified on staging" + +# 8. After production deployment +jira issue move PROJ-123 "Closed" --comment "Deployed to production in release v2.1.1" +``` + +### Feature Development Workflow + +```bash +# 1. Create story +jira issue create --type Story --summary "Add dark mode toggle" --body "..." + +# 2. Break down into subtasks (if needed) +jira issue create --type Subtask --parent PROJ-123 --summary "Create dark mode CSS" +jira issue create --type Subtask --parent PROJ-123 --summary "Add toggle component" +jira issue create --type Subtask --parent PROJ-123 --summary "Persist user preference" + +# 3. Work through each subtask +jira issue move PROJ-124 "In Progress" +# ... develop ... +jira issue move PROJ-124 "Done" + +# 4. When all subtasks done, complete parent story +jira issue move PROJ-123 "Done" +``` + +### Blocked Issue Workflow + +```bash +# 1. Working on issue, discover blocker +jira issue move PROJ-123 "Blocked" --comment "Blocked by API issue PROJ-100" + +# 2. Link to blocking issue +jira issue link PROJ-123 PROJ-100 "is blocked by" + +# 3. When blocker resolved +jira issue move PROJ-123 "In Progress" --comment "Blocker resolved, resuming work" +``` + +## Bulk Operations + +### Moving Multiple Issues + +For sprint planning or cleanup: + +```bash +# Get list of issues +jira issue list --status "To Do" --plain + +# Move them (one at a time or use script) +jira issue move PROJ-123 "Backlog" +jira issue move PROJ-124 "Backlog" +jira issue move PROJ-125 "Backlog" +``` + +### Batch Assignment + +```bash +# Assign multiple issues to team member +jira issue assign PROJ-123 developer@example.com +jira issue assign PROJ-124 developer@example.com +jira issue assign PROJ-125 developer@example.com +``` + +## Viewing Workflow States + +### Available Transitions + +To see available transitions for an issue: +```bash +jira issue move PROJ-123 +``` + +This shows all possible next states based on current state and workflow configuration. + +### Issue History + +View all changes to an issue: +```bash +jira issue view PROJ-123 --plain +``` + +Scroll to history section to see all transitions, edits, and comments. + +## Best Practices + +1. **Update issues regularly** - Keep status current +2. **Add meaningful comments** - Explain changes and decisions +3. **Link related work** - Connect PRs, issues, and documentation +4. **Follow workflow** - Don't skip states +5. **Use appropriate transitions** - Don't move directly from "To Do" to "Done" +6. **Maintain traceability** - Always reference issue keys in commits/PRs +7. **Close issues promptly** - Don't leave completed work open +8. **Add resolution when closing** - Document why/how resolved + +## Automation Integration + +### Git Hooks + +Add to `.git/hooks/commit-msg`: +```bash +#!/bin/bash +commit_msg_file=$1 +commit_msg=$(cat "$commit_msg_file") + +# Check if commit message contains issue key +if ! echo "$commit_msg" | grep -qE "PROJ-[0-9]+"; then + echo "ERROR: Commit message must reference a Jira issue (e.g., PROJ-123)" + exit 1 +fi +``` + +### CI/CD Integration + +In your CI/CD pipeline: +```bash +# Extract issue key from branch or commit +ISSUE_KEY=$(git branch --show-current | grep -oE "PROJ-[0-9]+") + +# Add deployment comment +jira issue comment "$ISSUE_KEY" "Deployed to staging by CI/CD pipeline #${BUILD_NUMBER}" + +# Optionally transition +jira issue move "$ISSUE_KEY" "Testing" --comment "Automated deployment to staging" +``` + +## Definition of Done + +- [ ] Understand the complete issue lifecycle +- [ ] Can create issues with proper details +- [ ] Can assign issues to self and others +- [ ] Can transition issues through workflow states +- [ ] Can add comments and updates to issues +- [ ] Can link related issues and PRs +- [ ] Can close issues with appropriate resolution +- [ ] Understand when to use each workflow state +- [ ] Know how to handle blocked or problematic issues +- [ ] Can integrate Jira updates with development workflow + +## Troubleshooting + +**Issue won't transition:** +- Check if you have required fields filled +- Verify you have permission for that transition +- Some transitions require specific roles +- Try interactive mode to see available options + +**Can't find issue:** +- Verify issue key is correct (PROJ-123) +- Check if you have access to that project +- Ensure issue hasn't been deleted + +**Workflow differs from docs:** +- Workflows are customizable per project +- Run `jira issue move PROJ-123` to see your project's workflow +- Contact Jira admin for workflow documentation + +## Next Steps + +- Use `/jira-sprint-planning` for sprint management +- Use `jira-query-builder` agent for finding issues +- Integrate with git workflows and CI/CD +- Set up automation for common transitions +- Create templates for different issue types diff --git a/commands/jira-setup.md b/commands/jira-setup.md new file mode 100644 index 0000000..5b72e1a --- /dev/null +++ b/commands/jira-setup.md @@ -0,0 +1,323 @@ +# Jira CLI Setup Command + +Initialize and configure jira-cli for seamless Jira integration. + +## Instructions + +Guide the user through the complete jira-cli setup process, from installation to configuration. + +### Step 1: Check Installation + +First, verify if jira-cli is installed: + +```bash +which jira +jira version +``` + +If not installed, provide platform-specific installation instructions: + +**macOS (Homebrew):** +```bash +brew install ankitpokhrel/jira-cli/jira-cli +``` + +**Linux (using install script):** +```bash +curl -sL https://raw.githubusercontent.com/ankitpokhrel/jira-cli/main/install.sh | sh +``` + +**Go install:** +```bash +go install github.com/ankitpokhrel/jira-cli/cmd/jira@latest +``` + +**Manual download:** +- Visit: https://github.com/ankitpokhrel/jira-cli/releases +- Download the appropriate binary for the user's platform +- Extract and move to PATH + +### Step 2: Gather Jira Information + +Ask the user for necessary Jira details: + +1. **Jira Installation Type** + - Cloud (https://yourcompany.atlassian.net) + - Server/Data Center (https://jira.yourcompany.com) + +2. **Jira Server URL** + - Full URL to their Jira instance + - Example: `https://company.atlassian.net` or `https://jira.company.com` + +3. **Authentication Method** + - **Cloud**: Typically uses API tokens + - **Server**: May use basic auth or PAT (Personal Access Token) + +4. **Project Key** + - Default project key (e.g., PROJ, DEV, TEAM) + - Users can configure multiple projects later + +### Step 3: Initialize Configuration + +Run the interactive initialization: + +```bash +jira init +``` + +This will prompt for: +1. Installation type (Cloud or Local) +2. Jira URL +3. Login email (for Cloud) or username (for Server) +4. API token or password +5. Default project + +**IMPORTANT**: Inform users: +- For **Jira Cloud**: They need to create an API token + - Go to: https://id.atlassian.com/manage-profile/security/api-tokens + - Click "Create API token" + - Give it a name (e.g., "jira-cli") + - Copy the token (they won't be able to see it again) + +- For **Jira Server**: They might need to enable API access or use credentials + +### Step 4: Set Environment Variables (Optional but Recommended) + +For enhanced security, users can set environment variables instead of storing credentials in config: + +```bash +# Add to ~/.bashrc or ~/.zshrc +export JIRA_API_TOKEN="your-api-token-here" +export JIRA_AUTH_TYPE="bearer" # For PAT authentication +``` + +### Step 5: Verify Configuration + +Test the configuration: + +```bash +# List projects to verify connection +jira project list --plain + +# List issues in default project +jira issue list --plain + +# View current configuration +cat ~/.config/.jira/.config.yml +``` + +If any command fails, troubleshoot: +- Check URL is correct (including https://) +- Verify API token is valid +- Ensure user has correct permissions +- Check network connectivity + +### Step 6: Configure Multiple Projects (Optional) + +For users working with multiple projects: + +1. **Create named config files:** + ```bash + jira init --config ~/.config/.jira/.config.project1.yml + jira init --config ~/.config/.jira/.config.project2.yml + ``` + +2. **Use different configs:** + ```bash + jira issue list -c ~/.config/.jira/.config.project1.yml + jira issue list -c ~/.config/.jira/.config.project2.yml + ``` + +3. **Set via environment variable:** + ```bash + export JIRA_CONFIG_FILE=~/.config/.jira/.config.project1.yml + jira issue list + ``` + +4. **Create aliases for convenience:** + ```bash + alias jira-proj1='jira -c ~/.config/.jira/.config.project1.yml' + alias jira-proj2='jira -c ~/.config/.jira/.config.project2.yml' + ``` + +### Step 7: Shell Completion (Optional) + +Enable shell completion for better UX: + +**Bash:** +```bash +echo 'eval "$(jira completion bash)"' >> ~/.bashrc +source ~/.bashrc +``` + +**Zsh:** +```bash +echo 'eval "$(jira completion zsh)"' >> ~/.zshrc +source ~/.zshrc +``` + +**Fish:** +```bash +jira completion fish > ~/.config/fish/completions/jira.fish +``` + +### Step 8: Test Common Operations + +Run through basic operations to ensure everything works: + +```bash +# 1. List recent issues +jira issue list --plain + +# 2. View a specific issue (use actual issue key from list) +jira issue view PROJ-123 --plain + +# 3. Check sprints (if using Scrum) +jira sprint list --plain + +# 4. View boards +jira board list --plain +``` + +## Troubleshooting + +### Common Issues and Solutions + +**1. "jira: command not found"** +- Solution: Install jira-cli using one of the methods above +- Verify installation: `which jira` +- Ensure binary is in PATH + +**2. "unauthorized" or "401" error** +- Solution: Check API token or credentials +- For Cloud: Regenerate API token at https://id.atlassian.com/manage-profile/security/api-tokens +- For Server: Verify username/password + +**3. "project not found" or "404" error** +- Solution: Verify project key is correct +- List available projects: `jira project list` +- Check user has access to project + +**4. "forbidden" or "403" error** +- Solution: User lacks permissions +- Contact Jira administrator +- Verify user is added to project + +**5. Configuration file not found** +- Solution: Run `jira init` to create config +- Check config location: `~/.config/.jira/.config.yml` +- Set custom location: `export JIRA_CONFIG_FILE=/path/to/config.yml` + +**6. SSL/TLS certificate errors (Server only)** +- Solution: For self-signed certs, may need to configure mtls +- Check with system administrator +- See: https://github.com/ankitpokhrel/jira-cli#mtls + +**7. Slow performance** +- Solution: Reduce query scope +- Use specific project filters +- Limit number of results: Add `--limit` flag +- Use `--plain` instead of default interactive mode for scripts + +## Configuration File Structure + +The config file (`~/.config/.jira/.config.yml`) contains: + +```yaml +installation: Cloud # or Local for Server +server: https://company.atlassian.net +login: your-email@company.com # or username for Server +project: + key: PROJ + type: scrum # or kanban +``` + +Users can manually edit this file if needed. + +## Security Best Practices + +1. **Never commit config files** to version control + ```bash + echo ".jira/" >> ~/.gitignore + ``` + +2. **Use environment variables** for sensitive data + ```bash + export JIRA_API_TOKEN="token-here" + unset JIRA_API_TOKEN # Clear when done + ``` + +3. **Restrict config file permissions** + ```bash + chmod 600 ~/.config/.jira/.config.yml + ``` + +4. **Rotate API tokens** regularly + - Cloud: Regenerate at Atlassian + - Server: Update in settings + +5. **Use separate tokens** for different purposes + - Personal use + - CI/CD automation + - Shared scripts + +## Advanced Configuration + +### Custom Fields + +If using custom fields: + +```bash +jira init --custom-field-key=customfield_10001 +``` + +### Proxy Settings + +For corporate proxies: + +```bash +export HTTP_PROXY=http://proxy.company.com:8080 +export HTTPS_PROXY=http://proxy.company.com:8080 +jira issue list +``` + +### Debug Mode + +Enable debug output for troubleshooting: + +```bash +jira issue list --debug +``` + +## Definition of Done + +- [ ] jira-cli is installed and accessible in PATH +- [ ] Configuration file created with correct Jira URL and credentials +- [ ] Successfully authenticated to Jira instance +- [ ] Can list projects: `jira project list --plain` +- [ ] Can list issues: `jira issue list --plain` +- [ ] Can view an issue: `jira issue view PROJ-123 --plain` +- [ ] Shell completion configured (optional) +- [ ] Multiple project configs set up (if needed) +- [ ] User understands how to use --plain and --raw flags +- [ ] Security best practices discussed and implemented + +## Next Steps + +After successful setup, suggest: + +1. **Explore commands**: Run `jira --help` to see all available commands +2. **Use agents**: Leverage the jira-manager, jira-sprint-master, and jira-query-builder agents +3. **Create workflows**: Use `/jira-issue-workflow` for common issue operations +4. **Sprint planning**: Use `/jira-sprint-planning` for agile ceremonies +5. **Learn JQL**: Use jira-query-builder agent for advanced queries + +## Notes + +- Configuration is stored in `~/.config/.jira/` +- API tokens for Cloud never expire unless revoked +- Server tokens may have expiration policies +- Users can have multiple config files for different projects +- The `--config` or `-c` flag allows switching between configurations + +Inform the user that they can always run `jira init` again to reconfigure or add new projects. diff --git a/commands/jira-sprint-planning.md b/commands/jira-sprint-planning.md new file mode 100644 index 0000000..0127046 --- /dev/null +++ b/commands/jira-sprint-planning.md @@ -0,0 +1,731 @@ +# Jira Sprint Planning Command + +Sprint planning, backlog grooming, and sprint execution workflows using jira-cli. + +## Instructions + +Guide users through complete agile sprint ceremonies and workflows using jira-cli. + +## Sprint Lifecycle + +``` +Backlog Grooming → Sprint Planning → Sprint Execution → Daily Standups → Sprint Review → Retrospective → Repeat +``` + +## Phase 1: Backlog Grooming + +Prepare the backlog before sprint planning. + +### Review and Prioritize Backlog + +**View all backlog items:** +```bash +jira issue list --status "To Do" --plain +``` + +**View by priority:** +```bash +jira issue list --status "To Do" --priority High,Critical --plain +``` + +**View unestimated stories:** +```bash +jira issue list --status "To Do" --jql "\"Story Points\" IS EMPTY" --plain +``` + +### Grooming Checklist + +For each backlog item, ensure: + +1. **Clear description** - Well-written user story or bug report + ```bash + jira issue view PROJ-123 --plain + ``` + +2. **Acceptance criteria defined** - What "done" looks like + ```bash + jira issue edit PROJ-123 --body " + ## Acceptance Criteria + - [ ] User can login with email + - [ ] Password validation in place + - [ ] Error messages displayed + " + ``` + +3. **Properly sized** - Story points estimated + ```bash + jira issue edit PROJ-123 --custom story_points=5 + ``` + +4. **Dependencies identified** - Link blocking/blocked issues + ```bash + jira issue link PROJ-123 PROJ-100 "is blocked by" + ``` + +5. **Questions answered** - No unknowns + ```bash + jira issue comment PROJ-123 "Clarified with product: should support OAuth and email/password" + ``` + +### Grooming Activities + +**Break down large stories:** +```bash +# Create subtasks for large story +jira issue create --type Subtask --parent PROJ-123 --summary "Create database schema" +jira issue create --type Subtask --parent PROJ-123 --summary "Implement API endpoints" +jira issue create --type Subtask --parent PROJ-123 --summary "Add UI components" +``` + +**Add labels for organization:** +```bash +jira issue edit PROJ-123 --label frontend,high-priority +``` + +**Update priority based on business value:** +```bash +jira issue edit PROJ-123 --priority High +``` + +## Phase 2: Sprint Planning + +Plan the upcoming sprint iteration. + +### Pre-Planning: Check Current Sprint + +**View active sprint:** +```bash +jira sprint list --state active --plain +``` + +**Check sprint progress:** +```bash +jira sprint view --plain +``` + +**Identify incomplete items (to carry over):** +```bash +jira issue list --status "In Progress,To Do" --plain +``` + +### Sprint Planning Meeting + +#### Step 1: Set Sprint Goal + +Define the sprint objective (document outside Jira or in sprint description): +- What is the primary goal? +- What value will we deliver? +- What will we demo? + +#### Step 2: Review Team Capacity + +Calculate available capacity: +- Number of team members +- Days in sprint +- Planned time off +- Other commitments + +Example: 5 developers × 10 days × 6 hours = 300 story points capacity + +#### Step 3: Select Sprint Backlog + +**List candidate stories (prioritized backlog):** +```bash +jira issue list --status "To Do" --priority High,Medium --plain +``` + +**View details for consideration:** +```bash +jira issue view PROJ-123 --plain +``` + +**Add items to sprint:** +```bash +jira sprint add PROJ-123 PROJ-124 PROJ-125 +``` + +**Continue until capacity reached.** + +#### Step 4: Assign Initial Ownership + +**View sprint issues:** +```bash +jira sprint view --plain +``` + +**Assign to team members:** +```bash +jira issue assign PROJ-123 developer1@example.com +jira issue assign PROJ-124 developer2@example.com +jira issue assign PROJ-125 @me +``` + +#### Step 5: Verify Sprint Commitment + +**Calculate total story points:** +```bash +# List all sprint issues with story points +jira issue list --jql "sprint = " --raw +``` + +Parse and sum story points to verify it matches capacity. + +**Check for blockers:** +```bash +jira issue list --status Blocked --plain +``` + +Resolve blockers before sprint starts. + +### Sprint Planning Checklist + +- [ ] Sprint goal defined and communicated +- [ ] Team capacity calculated +- [ ] Backlog items selected and added to sprint +- [ ] Total story points ≤ team capacity +- [ ] All items meet Definition of Ready +- [ ] Initial assignments made +- [ ] Dependencies identified and managed +- [ ] No critical blockers +- [ ] Team agrees on commitment + +### Definition of Ready + +Before adding to sprint, ensure: +- [ ] User story clearly written +- [ ] Acceptance criteria defined +- [ ] Story pointed/estimated +- [ ] Dependencies identified +- [ ] Technical approach discussed +- [ ] No major unknowns + +## Phase 3: Sprint Execution + +Day-to-day sprint activities. + +### Daily Workflow + +**Morning: Check your work:** +```bash +jira issue list --assignee @me --status "In Progress,To Do" --plain +``` + +**Start working on item:** +```bash +jira issue move PROJ-123 "In Progress" --comment "Starting work on authentication" +``` + +**Throughout day: Update progress:** +```bash +jira issue comment PROJ-123 "Implemented login form, working on validation" +``` + +**End of day: Update status:** +```bash +jira issue comment PROJ-123 "Completed form validation, ready for API integration tomorrow" +``` + +**When blocked:** +```bash +jira issue move PROJ-123 "Blocked" --comment "Waiting for API specification from backend team" +jira issue link PROJ-123 PROJ-100 "is blocked by" +``` + +### Sprint Monitoring + +**Check sprint progress:** +```bash +jira sprint view --plain +``` + +**Identify at-risk items:** +```bash +jira issue list --status "To Do" --priority High --plain +``` + +**Find blocked issues:** +```bash +jira issue list --status Blocked --plain +``` + +**Check unassigned work:** +```bash +jira issue list --assignee EMPTY --status "To Do" --plain +``` + +### Mid-Sprint Adjustments + +**Add urgent issues (if capacity allows):** +```bash +jira sprint add PROJ-130 +jira issue assign PROJ-130 @me +jira issue move PROJ-130 "In Progress" +``` + +**Remove items if overcommitted:** +```bash +# Remove from sprint (moves back to backlog) +jira sprint remove PROJ-125 +``` + +## Phase 4: Daily Standup + +Quick daily synchronization. + +### Standup Report Generation + +**My yesterday/today/blockers:** +```bash +# What I completed yesterday +jira issue list --assignee @me --status Done --jql "updated >= -1d" --plain + +# What I'm working on today +jira issue list --assignee @me --status "In Progress" --plain + +# My blockers +jira issue list --assignee @me --status Blocked --plain +``` + +### Team Status + +**Overall sprint progress:** +```bash +jira sprint view --plain +``` + +**Team workload:** +```bash +jira issue list --status "In Progress" --plain +``` + +**Blockers across team:** +```bash +jira issue list --status Blocked --plain +``` + +### Standup Best Practices + +1. **Keep it brief** - 15 minutes max +2. **Focus on progress** - What's done, what's next +3. **Identify blockers** - Not problem-solving session +4. **Update Jira before standup** - Issues reflect current state +5. **Follow up separately** - Deep discussions after standup + +## Phase 5: Sprint Review + +Demonstrate completed work. + +### Pre-Review Preparation + +**Completed items for demo:** +```bash +jira issue list --status Done --jql "sprint = " --plain +``` + +**Verify all done items meet Definition of Done:** +```bash +jira issue view PROJ-123 --plain +``` + +Check: +- Acceptance criteria met +- Tested and working +- Deployed (if applicable) +- Documented + +### Review Metrics + +**Sprint completion rate:** +```bash +# Total issues in sprint +jira issue list --jql "sprint = " --raw + +# Completed issues +jira issue list --jql "sprint = AND status = Done" --raw + +# Calculate percentage +``` + +**Story points completed:** +```bash +# Sum story points of completed issues +jira issue list --jql "sprint = AND status = Done" --raw | grep storyPoints +``` + +**Issue breakdown:** +```bash +# By type +jira issue list --jql "sprint = " --plain | grep -c Story +jira issue list --jql "sprint = " --plain | grep -c Bug +jira issue list --jql "sprint = " --plain | grep -c Task +``` + +### Incomplete Work + +**Items not finished:** +```bash +jira issue list --jql "sprint = AND status != Done" --plain +``` + +**Move to next sprint or backlog:** +```bash +# Move to next sprint +jira sprint add PROJ-125 PROJ-126 + +# Or move back to backlog +jira issue edit PROJ-127 --status "To Do" +``` + +### Review Artifacts + +Document: +- Sprint goal achievement (met/not met) +- Velocity (story points completed) +- Completed items +- Demo feedback +- Incomplete items and reasons + +## Phase 6: Sprint Retrospective + +Reflect and improve. + +### Retrospective Data Gathering + +**Sprint metrics:** +```bash +# All sprint issues +jira issue list --jql "sprint = " --plain + +# Completed work +jira issue list --jql "sprint = AND status = Done" --plain + +# Issues that were blocked +jira issue list --jql "sprint = AND status was Blocked" --plain +``` + +### Retrospective Topics + +1. **What went well?** + - High velocity + - Good collaboration + - Smooth deployments + +2. **What could be improved?** + - Too many blockers + - Underestimated complexity + - Scope creep + +3. **Action items** + - Create issues for improvements + ```bash + jira issue create --type Task --summary "Improve estimation process" --label retrospective-action + ``` + +### Track Retrospective Actions + +**Create improvement tasks:** +```bash +jira issue create \ + --type Task \ + --summary "Set up automated testing pipeline" \ + --label retrospective-action,process-improvement \ + --assignee teamlead@example.com +``` + +**Review previous retrospective actions:** +```bash +jira issue list --label retrospective-action --status "To Do,In Progress" --plain +``` + +## Sprint Metrics and Reporting + +### Velocity Tracking + +**Last 3 sprints velocity:** +```bash +# Sprint 1 +jira issue list --jql "sprint = AND status = Done" --raw | grep storyPoints + +# Sprint 2 +jira issue list --jql "sprint = AND status = Done" --raw | grep storyPoints + +# Sprint 3 (current) +jira issue list --jql "sprint = AND status = Done" --raw | grep storyPoints +``` + +Calculate average for future planning. + +### Burndown Tracking + +**Remaining work over time:** +```bash +# At sprint start: Total story points +# Daily: Remaining story points +jira issue list --jql "sprint = AND status != Done" --raw | grep storyPoints +``` + +Track daily to create burndown chart externally. + +### Quality Metrics + +**Bug rate:** +```bash +# Bugs in sprint +jira issue list --jql "sprint = AND type = Bug" --raw + +# Bugs found post-deployment +jira issue list --jql "type = Bug AND created >= -14d AND labels = production" --raw +``` + +**Rework rate:** +```bash +# Issues returned from review +jira issue list --jql "status was 'In Review' AND status = 'In Progress'" --raw +``` + +## Epic Management + +Epics span multiple sprints. + +### Creating Epic + +```bash +jira epic create --name "User Authentication System" --summary "Implement complete auth system" +``` + +### Planning Epic Across Sprints + +**View epic details:** +```bash +jira epic view PROJ-100 --plain +``` + +**List all epic stories:** +```bash +jira issue list --jql "\"Epic Link\" = PROJ-100" --plain +``` + +**Distribute across sprints:** +```bash +# Sprint 1: Foundation +jira sprint add PROJ-101 PROJ-102 + +# Sprint 2: Core features +jira sprint add PROJ-103 PROJ-104 + +# Sprint 3: Polish +jira sprint add PROJ-105 PROJ-106 +``` + +### Epic Progress Tracking + +**Completion status:** +```bash +# Total issues in epic +jira issue list --jql "\"Epic Link\" = PROJ-100" --raw + +# Completed issues +jira issue list --jql "\"Epic Link\" = PROJ-100 AND status = Done" --raw +``` + +## Common Sprint Patterns + +### Pattern 1: Standard Two-Week Sprint + +```bash +# Week 1 Monday: Sprint Planning +jira sprint list --state future --plain # Get next sprint ID +jira issue list --status "To Do" --priority High --plain # Review backlog +jira sprint add PROJ-123 PROJ-124 PROJ-125 # Add to sprint +jira issue assign PROJ-123 @me # Assign work + +# Daily: Standups and updates +jira issue list --assignee @me --status "In Progress" --plain + +# Week 2 Friday: Sprint Review & Retrospective +jira sprint view --plain # Review progress +jira issue list --jql "sprint = AND status != Done" --plain # Incomplete items + +# Move incomplete items +jira sprint add PROJ-126 +``` + +### Pattern 2: Continuous Flow (Kanban) + +```bash +# Regular backlog grooming +jira issue list --status "To Do" --plain + +# Pull work as capacity allows +jira issue assign PROJ-123 @me +jira issue move PROJ-123 "In Progress" + +# Track WIP limits +jira issue list --status "In Progress" --plain +``` + +### Pattern 3: Rapid Iteration (One-Week Sprints) + +```bash +# Monday: Quick planning +jira sprint add PROJ-123 PROJ-124 PROJ-125 + +# Tuesday-Thursday: Execute +jira issue move PROJ-123 "In Progress" +# ... work ... +jira issue move PROJ-123 "Done" + +# Friday: Review and retro (combined) +jira sprint view --plain +``` + +## Automation and Scripts + +### Sprint Start Script + +```bash +#!/bin/bash +# sprint-start.sh + +SPRINT_ID=$1 + +echo "Starting Sprint $SPRINT_ID" + +# List sprint contents +echo "Sprint Backlog:" +jira sprint view "$SPRINT_ID" --plain + +# Check for blockers +echo -e "\nChecking for blockers:" +jira issue list --status Blocked --plain + +# Team assignments +echo -e "\nTeam Workload:" +jira issue list --jql "sprint = $SPRINT_ID" --plain +``` + +### Daily Status Script + +```bash +#!/bin/bash +# daily-status.sh + +echo "===== My Work =====" +echo "In Progress:" +jira issue list --assignee @me --status "In Progress" --plain + +echo -e "\nTo Do:" +jira issue list --assignee @me --status "To Do" --plain + +echo -e "\nBlocked:" +jira issue list --assignee @me --status Blocked --plain + +echo -e "\n===== Sprint Progress =====" +jira sprint view --plain +``` + +### Sprint End Script + +```bash +#!/bin/bash +# sprint-end.sh + +SPRINT_ID=$1 +NEXT_SPRINT_ID=$2 + +echo "Completing Sprint $SPRINT_ID" + +# Completed items +echo "Completed Issues:" +jira issue list --jql "sprint = $SPRINT_ID AND status = Done" --plain + +# Incomplete items +echo -e "\nIncomplete Issues:" +INCOMPLETE=$(jira issue list --jql "sprint = $SPRINT_ID AND status != Done" --raw) +echo "$INCOMPLETE" + +# Move incomplete to next sprint +echo -e "\nMoving incomplete items to Sprint $NEXT_SPRINT_ID" +# Extract issue keys and move (requires jq) +echo "$INCOMPLETE" | jq -r '.issues[].key' | while read issue; do + jira sprint add "$NEXT_SPRINT_ID" "$issue" +done +``` + +## Best Practices + +### Sprint Planning + +1. **Don't overcommit** - Use 80% of capacity +2. **Balance work types** - Mix of features, bugs, tech debt +3. **Consider dependencies** - Don't block yourself +4. **Include buffer** - Time for unexpected issues +5. **Get team buy-in** - Everyone agrees on commitment + +### Sprint Execution + +1. **Update Jira daily** - Keep status current +2. **Communicate blockers** - Immediately when stuck +3. **Focus on sprint goal** - Avoid scope creep +4. **Swarm on blockers** - Help unblock teammates +5. **Demo early and often** - Get feedback during sprint + +### Sprint Ceremonies + +1. **Time-box meetings** - Respect team's time +2. **Come prepared** - Review work before meetings +3. **Stay focused** - Avoid rabbit holes +4. **Document decisions** - Record in Jira or wiki +5. **Action all items** - Every decision becomes a task + +## Definition of Done + +### Story Level + +- [ ] Code complete and reviewed +- [ ] Unit tests written and passing +- [ ] Integration tests passing +- [ ] Documentation updated +- [ ] Deployed to staging +- [ ] QA approved +- [ ] Acceptance criteria met + +### Sprint Level + +- [ ] Sprint goal achieved +- [ ] All committed stories done +- [ ] Demo completed +- [ ] Stakeholder feedback gathered +- [ ] Retrospective conducted +- [ ] Velocity recorded +- [ ] Next sprint planned + +## Troubleshooting + +**Sprint not showing:** +- Check board configuration +- Verify sprint is created for correct board +- Ensure you have permissions + +**Can't add issues to sprint:** +- Check if issue is in correct project +- Verify issue isn't in another sprint +- Ensure sprint isn't closed + +**Sprint metrics incorrect:** +- Verify story points field is configured +- Check custom field names +- May need admin to configure + +**Team velocity varies wildly:** +- Review estimation process +- Check for consistent team composition +- Consider external factors (holidays, etc.) + +## Next Steps + +- Use `jira-query-builder` agent for advanced sprint queries +- Set up automation scripts for common tasks +- Create dashboards for sprint metrics +- Integrate with CI/CD for automated updates +- Establish team norms and Definition of Done diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..30d655e --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,73 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:yebot/rad-cc-plugins:plugins/jira-cli", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "dc3130bc4b12cbfbffb735505190e0453567e227", + "treeHash": "472332ad844082ae86a431bf509907fdefd63f9e07f15d73b058aaf28c28cb09", + "generatedAt": "2025-11-28T10:29:11.229656Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "jira-cli", + "description": "Jira CLI Expert - Comprehensive toolkit for managing Jira issues, sprints, and workflows using ankitpokhrel/jira-cli with minimal trial and error", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "51879a99e59bc48da16d7f3d3bb3a4c8686f150e1e47345df4dd4620ebc8fa23" + }, + { + "path": "agents/jira-query-builder.md", + "sha256": "c12340673235b3e16917a532e88d88d6268b5636a5b2f2a4467fe10a310a7b07" + }, + { + "path": "agents/jira-sprint-master.md", + "sha256": "e4c9b243065685dee8fb986f6a33ad6c98dc84b9f7126ebca4cae3b165cfab35" + }, + { + "path": "agents/jira-manager.md", + "sha256": "68b341a9987b006a2472fccc9366891e5ef2d6d1eb73cbc7731e04d57b9e9594" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "3a25323f171cba8a95acc3880d1a834f183536e7612b321341178eca288deb3b" + }, + { + "path": "commands/jira-issue-workflow.md", + "sha256": "f912194ab281b6ab077ef9e26e763ed4559c5f8da0b390f93d52ba48840cf780" + }, + { + "path": "commands/jira-setup.md", + "sha256": "64d2581811f5d5fa470a339d7a4c8b6ee84293fb570245170c56cc6042169181" + }, + { + "path": "commands/jira-sprint-planning.md", + "sha256": "c08c4cd8dbb9770bc6217859a51a928841643410bd537c2627974721834f261e" + }, + { + "path": "skills/jira-workflow-transitions/SKILL.md", + "sha256": "bfd5a02d53823c763c08fc909be45e69217498d2a7d0d17b1de6e7a575221d40" + }, + { + "path": "skills/jira-jql-patterns/SKILL.md", + "sha256": "02d67f0a771eb7827d8eece3f703eb0968d32dc29b4bada896deaa29c3fcd4bc" + } + ], + "dirSha256": "472332ad844082ae86a431bf509907fdefd63f9e07f15d73b058aaf28c28cb09" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/jira-jql-patterns/SKILL.md b/skills/jira-jql-patterns/SKILL.md new file mode 100644 index 0000000..d64a332 --- /dev/null +++ b/skills/jira-jql-patterns/SKILL.md @@ -0,0 +1,668 @@ +# JQL Patterns Skill + +Master JQL (Jira Query Language) query construction for advanced issue filtering and reporting. + +## Overview + +JQL is Jira's powerful query language for finding issues. This skill provides patterns and templates for constructing effective queries using jira-cli. + +## Basic JQL Structure + +``` +field operator value [AND|OR field operator value] +``` + +## Essential Field Reference + +### Issue Fields + +| Field | Type | Example | +|-------|------|---------| +| `project` | Text | `project = PROJ` | +| `key` | Text | `key = PROJ-123` | +| `summary` | Text | `summary ~ "login"` | +| `description` | Text | `description ~ "error"` | +| `status` | Text | `status = "In Progress"` | +| `priority` | Text | `priority IN (High, Critical)` | +| `type` | Text | `type = Bug` | +| `labels` | List | `labels = urgent` | +| `component` | Text | `component = Backend` | +| `fixVersion` | Version | `fixVersion = "1.0"` | +| `resolution` | Text | `resolution = Fixed` | + +### People Fields + +| Field | Type | Example | +|-------|------|---------| +| `assignee` | User | `assignee = currentUser()` | +| `reporter` | User | `reporter = "user@example.com"` | +| `creator` | User | `creator = currentUser()` | +| `watcher` | User | `watcher = currentUser()` | + +### Date Fields + +| Field | Type | Example | +|-------|------|---------| +| `created` | Date | `created >= -7d` | +| `updated` | Date | `updated >= startOfWeek()` | +| `resolved` | Date | `resolved >= "2024-01-01"` | +| `duedate` | Date | `duedate <= now()` | + +### Agile Fields + +| Field | Type | Example | +|-------|------|---------| +| `sprint` | Sprint | `sprint = 123` | +| `"Epic Link"` | Epic | `"Epic Link" = PROJ-100` | +| `"Story Points"` | Number | `"Story Points" > 5` | + +## Operators Reference + +### Equality + +- `=` - Equals +- `!=` - Not equals +- `IN` - In list +- `NOT IN` - Not in list + +### Comparison + +- `>` - Greater than +- `>=` - Greater than or equal +- `<` - Less than +- `<=` - Less than or equal + +### Text Search + +- `~` - Contains (case-insensitive) +- `!~` - Does not contain +- `IS` - For checking null/empty +- `IS NOT` - For checking not null/empty + +### Special + +- `IS EMPTY` - Field has no value +- `IS NOT EMPTY` - Field has value +- `WAS` - Historical value +- `CHANGED` - Field was changed + +## JQL Functions + +### User Functions + +```jql +assignee = currentUser() +reporter = currentUser() +watcher = currentUser() +assignee IN membersOf("developers") +``` + +### Date Functions + +```jql +created >= startOfDay() +created <= endOfDay() +created >= startOfWeek() +created >= startOfMonth() +created >= startOfYear() + +updated >= startOfDay(-7) # 7 days ago +duedate <= endOfWeek(1) # End of next week +``` + +### Sprint Functions + +```jql +sprint IN openSprints() +sprint IN closedSprints() +sprint IN futureSprints() +``` + +## Common Query Patterns + +### My Work Queries + +**Current work:** +```jql +assignee = currentUser() AND status NOT IN (Done, Closed) +``` + +**Recently completed:** +```jql +assignee = currentUser() AND status = Done AND resolved >= -7d +``` + +**Reported by me:** +```jql +reporter = currentUser() AND status NOT IN (Done, Closed) +``` + +**Watching:** +```jql +watcher = currentUser() AND status NOT IN (Done, Closed) +``` + +### Priority Queries + +**Critical and high priority open:** +```jql +priority IN (Critical, High) AND status NOT IN (Done, Closed, Resolved) +``` + +**Urgent bugs:** +```jql +type = Bug AND priority = Critical AND status NOT IN (Done, Closed) +``` + +**Prioritized backlog:** +```jql +status = "To Do" AND priority IN (High, Medium) ORDER BY priority DESC +``` + +### Time-Based Queries + +**Created today:** +```jql +created >= startOfDay() +``` + +**Updated this week:** +```jql +updated >= startOfWeek() +``` + +**Created in last 30 days:** +```jql +created >= -30d +``` + +**Overdue issues:** +```jql +duedate < now() AND status NOT IN (Done, Closed) +``` + +**Due this week:** +```jql +duedate >= startOfWeek() AND duedate <= endOfWeek() +``` + +**Stale issues (not updated in 90 days):** +```jql +updated <= -90d AND status NOT IN (Done, Closed) +``` + +### Team Queries + +**Unassigned issues:** +```jql +assignee IS EMPTY AND status = "To Do" +``` + +**Team workload:** +```jql +assignee IN (user1@example.com, user2@example.com) AND status IN ("In Progress", "To Do") +``` + +**Blocked issues:** +```jql +status = Blocked OR labels = blocked +``` + +**Issues needing review:** +```jql +status = "In Review" AND assignee IS NOT EMPTY +``` + +### Sprint Queries + +**Current sprint:** +```jql +sprint IN openSprints() +``` + +**Current sprint for project:** +```jql +project = PROJ AND sprint IN openSprints() +``` + +**Specific sprint:** +```jql +sprint = 123 +``` + +**Issues without sprint:** +```jql +type IN (Story, Bug, Task) AND sprint IS EMPTY +``` + +**Incomplete sprint items:** +```jql +sprint = 123 AND status NOT IN (Done, Closed) +``` + +### Epic Queries + +**All issues in epic:** +```jql +"Epic Link" = PROJ-100 +``` + +**Completed epic issues:** +```jql +"Epic Link" = PROJ-100 AND status = Done +``` + +**Issues without epic:** +```jql +type = Story AND "Epic Link" IS EMPTY +``` + +### Bug Tracking Queries + +**Open bugs:** +```jql +type = Bug AND status NOT IN (Done, Closed, "Won't Fix") +``` + +**Critical production bugs:** +```jql +type = Bug AND priority = Critical AND labels = production AND status NOT IN (Done, Closed) +``` + +**Bugs by component:** +```jql +type = Bug AND component = Backend AND status NOT IN (Done, Closed) +``` + +**Recently fixed bugs:** +```jql +type = Bug AND status = Done AND resolved >= -7d +``` + +**Regression bugs:** +```jql +type = Bug AND labels = regression AND status NOT IN (Done, Closed) +``` + +### Story Queries + +**Ready for development:** +```jql +type = Story AND status = "To Do" AND "Story Points" IS NOT EMPTY +``` + +**Unestimated stories:** +```jql +type = Story AND "Story Points" IS EMPTY AND status = "To Do" +``` + +**Large stories (need breakdown):** +```jql +type = Story AND "Story Points" >= 13 +``` + +### Component Queries + +**Frontend issues:** +```jql +component = Frontend AND status NOT IN (Done, Closed) +``` + +**Backend bugs:** +```jql +component = Backend AND type = Bug AND status NOT IN (Done, Closed) +``` + +**Issues without component:** +```jql +component IS EMPTY AND type IN (Story, Bug, Task) +``` + +### Label Queries + +**Technical debt:** +```jql +labels = tech-debt AND status NOT IN (Done, Closed) +``` + +**Multiple labels:** +```jql +labels IN (urgent, critical) AND status NOT IN (Done, Closed) +``` + +**Issues without labels:** +```jql +labels IS EMPTY AND type IN (Story, Bug) +``` + +## Advanced Patterns + +### Complex Logic with Parentheses + +```jql +project = PROJ AND +(priority = Critical OR labels = urgent) AND +status NOT IN (Done, Closed) +ORDER BY created DESC +``` + +### Historical Queries + +**Issues that were in progress:** +```jql +status WAS "In Progress" DURING (-7d, now()) +``` + +**Issues that changed priority:** +```jql +priority CHANGED DURING (-30d, now()) +``` + +**Issues moved to done this week:** +```jql +status CHANGED TO Done DURING (startOfWeek(), now()) +``` + +### Negative Queries + +**Not assigned to specific team:** +```jql +assignee NOT IN membersOf("qa-team") +``` + +**Exclude certain statuses:** +```jql +status NOT IN (Done, Closed, "Won't Fix", Duplicate) +``` + +**Not labeled:** +```jql +labels IS EMPTY +``` + +### Multi-Project Queries + +**Across projects:** +```jql +project IN (PROJ1, PROJ2, PROJ3) AND assignee = currentUser() +``` + +**All projects bugs:** +```jql +type = Bug AND priority = Critical AND status NOT IN (Done, Closed) +``` + +## Sorting Patterns + +### Single Sort + +```jql +ORDER BY priority DESC +ORDER BY created ASC +ORDER BY updated DESC +ORDER BY duedate ASC +``` + +### Multiple Sort + +```jql +ORDER BY priority DESC, created ASC +ORDER BY status ASC, priority DESC, updated DESC +ORDER BY duedate ASC, priority DESC +``` + +## Using with jira-cli + +### Basic Query + +```bash +jira issue list --jql "assignee = currentUser() AND status = 'In Progress'" +``` + +### Multi-line for Readability + +```bash +jira issue list --jql "\ + project = PROJ AND \ + status IN ('In Progress', 'In Review') AND \ + assignee = currentUser() AND \ + created >= -7d \ + ORDER BY priority DESC" +``` + +### With Output Formats + +```bash +# Human readable +jira issue list --jql "..." --plain + +# JSON for parsing +jira issue list --jql "..." --raw + +# CSV for export +jira issue list --jql "..." --csv +``` + +## Report Patterns + +### Sprint Velocity + +```jql +sprint = 123 AND status = Done +``` + +Sum story points from results. + +### Bug Trend + +```jql +type = Bug AND created >= -30d +``` + +```jql +type = Bug AND resolved >= -30d +``` + +Compare created vs resolved. + +### Team Performance + +```jql +assignee IN membersOf("dev-team") AND +status = Done AND +resolved >= startOfWeek() +``` + +### Epic Progress + +```jql +"Epic Link" = PROJ-100 +``` + +```jql +"Epic Link" = PROJ-100 AND status = Done +``` + +Calculate percentage complete. + +### Technical Debt Tracking + +```jql +labels = tech-debt AND +status NOT IN (Done, Closed) AND +created <= -90d +ORDER BY priority DESC, created ASC +``` + +## Query Optimization Tips + +### 1. Narrow by Project First + +❌ Slow: +```jql +status = "In Progress" +``` + +✅ Fast: +```jql +project = PROJ AND status = "In Progress" +``` + +### 2. Use Specific Operators + +❌ Slow: +```jql +summary ~ ".*login.*" +``` + +✅ Fast: +```jql +summary ~ "login" +``` + +### 3. Limit Results + +```bash +jira issue list --jql "..." --limit 100 +``` + +### 4. Use IS EMPTY Instead of Negation + +❌ Slower: +```jql +assignee != null +``` + +✅ Faster: +```jql +assignee IS NOT EMPTY +``` + +## Common Mistakes + +### Mistake 1: Missing Quotes + +❌ Wrong: +```jql +status = In Progress +``` + +✅ Correct: +```jql +status = "In Progress" +``` + +### Mistake 2: Wrong Function + +❌ Wrong: +```jql +assignee = me +``` + +✅ Correct: +```jql +assignee = currentUser() +``` + +### Mistake 3: Wrong Field Name + +❌ Wrong: +```jql +epic = PROJ-100 +``` + +✅ Correct: +```jql +"Epic Link" = PROJ-100 +``` + +### Mistake 4: Wrong Date Format + +❌ Wrong: +```jql +created > 7d +``` + +✅ Correct: +```jql +created >= -7d +``` + +## Debugging Queries + +### Step 1: Simplify + +Start with basic query: +```jql +project = PROJ +``` + +### Step 2: Add Conditions Incrementally + +```jql +project = PROJ AND status = "In Progress" +``` + +```jql +project = PROJ AND status = "In Progress" AND assignee = currentUser() +``` + +### Step 3: Test Each Addition + +Run query after each change to identify issues. + +### Step 4: Check Field Names + +Verify custom field names in Jira UI. + +### Step 5: Use --debug + +```bash +jira issue list --jql "..." --debug +``` + +## Saving Common Queries + +### Shell Aliases + +```bash +alias jira-my-work='jira issue list --jql "assignee = currentUser() AND status NOT IN (Done, Closed)" --plain' +alias jira-urgent='jira issue list --jql "priority IN (Critical, High) AND status NOT IN (Done, Closed)" --plain' +alias jira-sprint='jira issue list --jql "sprint IN openSprints()" --plain' +``` + +### Script Functions + +```bash +# Add to ~/.bashrc or ~/.zshrc +jira-find() { + local query="$1" + jira issue list --jql "summary ~ \"$query\" OR description ~ \"$query\"" --plain +} + +jira-my-bugs() { + jira issue list --jql "assignee = currentUser() AND type = Bug AND status NOT IN (Done, Closed)" --plain +} + +jira-overdue() { + jira issue list --jql "duedate < now() AND status NOT IN (Done, Closed)" --plain +} +``` + +## When to Use This Skill + +- User needs complex issue filtering +- Generating reports or metrics +- Finding issues across projects +- Historical queries +- Performance optimization needed +- Combining multiple criteria + +## Next Steps + +After mastering JQL: +1. Create saved queries for common needs +2. Integrate queries into automation scripts +3. Build dashboards based on queries +4. Share query templates with team +5. Document organization-specific patterns diff --git a/skills/jira-workflow-transitions/SKILL.md b/skills/jira-workflow-transitions/SKILL.md new file mode 100644 index 0000000..fa046fe --- /dev/null +++ b/skills/jira-workflow-transitions/SKILL.md @@ -0,0 +1,636 @@ +# Jira Workflow Transitions Skill + +Understanding and navigating Jira workflow states and transitions using jira-cli. + +## Overview + +Jira workflows define how issues move through different states from creation to completion. This skill helps you understand workflow concepts and effectively transition issues using jira-cli. + +## Workflow Fundamentals + +### What is a Workflow? + +A workflow is a set of **statuses** and **transitions** that an issue moves through during its lifecycle. + +**Status**: Current state of an issue (e.g., "To Do", "In Progress", "Done") + +**Transition**: Action that moves an issue from one status to another (e.g., "Start Progress", "Resolve") + +### Common Workflow Types + +**1. Basic Workflow** +``` +To Do → In Progress → Done +``` + +**2. Scrum Workflow** +``` +Backlog → To Do → In Progress → In Review → Done → Closed +``` + +**3. Complex Workflow** +``` +Open → In Progress → In Review → Testing → Blocked + ↓ + Done → Closed +``` + +## Standard Workflow States + +### Initial States + +**Backlog** +- Issues that might be worked on in future +- Not yet committed to a sprint +- May need grooming + +**To Do** +- Ready to be worked on +- Accepted into sprint or ready for picking up +- All requirements clear + +**Open** +- Newly created issue +- Needs triage or assignment +- May need more information + +### Active Work States + +**In Progress** +- Actively being worked on +- Assigned to someone +- Development underway + +**In Review** +- Code/work completed +- Awaiting peer review or approval +- Pull request open + +**Testing / QA** +- Under quality assurance testing +- Verification of acceptance criteria +- May be on staging environment + +### Blocked States + +**Blocked** +- Cannot proceed +- Waiting on external dependency +- Requires resolution of blocker + +**Waiting for Info** +- Need clarification or additional details +- Awaiting stakeholder input +- Cannot proceed without information + +### Completion States + +**Done** +- Work completed +- Accepted by product owner +- Meets Definition of Done + +**Closed** +- Fully resolved and closed +- No further action needed +- Archived state + +**Resolved** +- Issue addressed +- May need verification +- Intermediate completion state + +### Rejection States + +**Won't Fix** +- Decision not to address +- Out of scope +- Not a priority + +**Duplicate** +- Same as another issue +- Linked to original issue +- Closed as duplicate + +**Cannot Reproduce** +- Bug cannot be reproduced +- Insufficient information +- May reopen if new info emerges + +## Transitioning Issues + +### Basic Transition + +```bash +jira issue move PROJ-123 +``` + +This opens an interactive menu showing available transitions. + +### Direct Transition + +```bash +jira issue move PROJ-123 "In Progress" +``` + +Moves directly to specified state if transition is available. + +### Transition with Comment + +```bash +jira issue move PROJ-123 "Done" --comment "Completed feature implementation. Ready for deployment." +``` + +Always add comments to provide context about the transition. + +### Checking Available Transitions + +```bash +jira issue view PROJ-123 --plain +``` + +Shows current status and available next states. + +## Common Transition Patterns + +### Starting Work + +**From To Do to In Progress:** +```bash +# 1. Assign to yourself +jira issue assign PROJ-123 @me + +# 2. Move to In Progress +jira issue move PROJ-123 "In Progress" --comment "Starting work on authentication feature" +``` + +### Submitting for Review + +**From In Progress to In Review:** +```bash +jira issue move PROJ-123 "In Review" --comment "PR created: https://github.com/company/repo/pull/456" +``` + +### Handling Review Feedback + +**From In Review back to In Progress:** +```bash +jira issue move PROJ-123 "In Progress" --comment "Addressing review feedback: refactoring auth logic" +``` + +### Completing Work + +**From In Review to Done:** +```bash +jira issue move PROJ-123 "Done" --comment "PR merged. All acceptance criteria met." +``` + +### Handling Blockers + +**From In Progress to Blocked:** +```bash +jira issue move PROJ-123 "Blocked" --comment "Waiting for API spec from backend team" +jira issue link PROJ-123 PROJ-100 "is blocked by" +``` + +**From Blocked back to In Progress:** +```bash +jira issue move PROJ-123 "In Progress" --comment "Blocker resolved. Resuming work." +``` + +### Closing Issues + +**From Done to Closed:** +```bash +jira issue move PROJ-123 "Closed" --comment "Verified in production. No issues reported." +``` + +### Rejecting Issues + +**Won't Fix:** +```bash +jira issue move PROJ-123 "Closed" --resolution "Won't Fix" --comment "Decision: Out of scope for current roadmap" +``` + +**Duplicate:** +```bash +jira issue link PROJ-123 PROJ-100 "duplicates" +jira issue move PROJ-123 "Closed" --resolution "Duplicate" --comment "Duplicate of PROJ-100" +``` + +**Cannot Reproduce:** +```bash +jira issue move PROJ-123 "Closed" --resolution "Cannot Reproduce" --comment "Unable to reproduce. Please reopen with more details if issue persists." +``` + +## Workflow Best Practices + +### 1. Always Add Comments + +❌ Bad: +```bash +jira issue move PROJ-123 "In Progress" +``` + +✅ Good: +```bash +jira issue move PROJ-123 "In Progress" --comment "Starting with database schema design" +``` + +### 2. Update Before Transitioning + +```bash +# Update fields first +jira issue edit PROJ-123 --priority High +jira issue assign PROJ-123 @me + +# Then transition +jira issue move PROJ-123 "In Progress" +``` + +### 3. Link Related Work + +```bash +# When moving to review, link PR +jira issue move PROJ-123 "In Review" --comment "PR: https://github.com/company/repo/pull/456" + +# When blocking, link blocker +jira issue move PROJ-123 "Blocked" +jira issue link PROJ-123 PROJ-100 "is blocked by" +``` + +### 4. Don't Skip States + +❌ Bad (skipping review): +```bash +jira issue move PROJ-123 "Done" # Directly from In Progress +``` + +✅ Good (following workflow): +```bash +jira issue move PROJ-123 "In Review" # From In Progress +# ... review happens ... +jira issue move PROJ-123 "Done" # From In Review +``` + +### 5. Verify Before Completion + +Before moving to Done: +```bash +# Review issue details +jira issue view PROJ-123 --plain + +# Check acceptance criteria met +# Verify tests passing +# Confirm deployment successful + +# Then complete +jira issue move PROJ-123 "Done" --comment "All acceptance criteria met. Deployed to production." +``` + +## Workflow States by Issue Type + +### Bug Workflow + +``` +Open → In Progress → In Review → Testing → Fixed → Closed + ↓ + Cannot Reproduce + Won't Fix +``` + +**Key transitions:** +```bash +# Start fix +jira issue move BUG-123 "In Progress" --comment "Investigating root cause" + +# Submit fix +jira issue move BUG-123 "In Review" --comment "Fix PR: ..." + +# After QA +jira issue move BUG-123 "Fixed" --comment "Verified on staging" + +# After deployment +jira issue move BUG-123 "Closed" --comment "Fix deployed to production" +``` + +### Story Workflow + +``` +Backlog → To Do → In Progress → In Review → Done → Closed +``` + +**Key transitions:** +```bash +# Sprint planning +jira issue move STORY-123 "To Do" --comment "Added to Sprint 42" + +# Start development +jira issue move STORY-123 "In Progress" + +# Code review +jira issue move STORY-123 "In Review" --comment "PR: ..." + +# Accept story +jira issue move STORY-123 "Done" --comment "Demo approved by PO" +``` + +### Task Workflow + +``` +To Do → In Progress → Done +``` + +**Key transitions:** +```bash +# Simple workflow +jira issue move TASK-123 "In Progress" +# ... work ... +jira issue move TASK-123 "Done" +``` + +### Epic Workflow + +``` +To Do → In Progress → Done → Closed +``` + +**Epics transition when child stories complete:** +```bash +# Start epic when first story starts +jira issue move EPIC-100 "In Progress" + +# Complete epic when all stories done +jira issue move EPIC-100 "Done" --comment "All stories completed. Feature fully implemented." +``` + +## Handling Special Cases + +### Reopening Issues + +**Reopen a closed issue:** +```bash +jira issue move PROJ-123 "Reopened" --comment "Bug has reoccurred. New reproduction steps: ..." +``` + +Or back to original state: +```bash +jira issue move PROJ-123 "In Progress" --comment "Reopening to address regression" +``` + +### Moving Between Sprints + +```bash +# Issue incomplete at sprint end +jira issue move PROJ-123 "To Do" --comment "Moving to Sprint 43 due to blocker" +jira sprint add PROJ-123 +``` + +### Escalating Priority + +```bash +# Change priority +jira issue edit PROJ-123 --priority Critical + +# Add urgency label +jira issue edit PROJ-123 --label urgent + +# Move up in workflow if needed +jira issue move PROJ-123 "In Progress" --comment "Escalated to critical. Addressing immediately." +``` + +### Split Issues + +When an issue is too large: +```bash +# Create new issues +jira issue create --type Story --summary "Part 1: ..." --parent PROJ-123 +jira issue create --type Story --summary "Part 2: ..." --parent PROJ-123 + +# Close original or mark as epic +jira issue edit PROJ-123 --type Epic +``` + +## Workflow Automation + +### Git Integration + +**Pre-commit hook:** +```bash +#!/bin/bash +# Ensure commits reference Jira issue +if ! git log -1 --pretty=%B | grep -qE "PROJ-[0-9]+"; then + echo "ERROR: Commit must reference Jira issue" + exit 1 +fi +``` + +**Post-merge hook:** +```bash +#!/bin/bash +# Auto-transition after merge +ISSUE_KEY=$(git log -1 --pretty=%B | grep -oE "PROJ-[0-9]+") +if [ -n "$ISSUE_KEY" ]; then + jira issue move "$ISSUE_KEY" "Testing" --comment "Merged to main. Ready for QA." +fi +``` + +### CI/CD Integration + +**On deployment:** +```bash +#!/bin/bash +# Extract issue keys from commits since last deploy +ISSUES=$(git log --pretty=%B $LAST_TAG..HEAD | grep -oE "PROJ-[0-9]+" | sort -u) + +# Transition each issue +for issue in $ISSUES; do + jira issue move "$issue" "Testing" --comment "Deployed to staging by CI/CD pipeline" +done +``` + +### Scheduled Status Updates + +**Daily reminder script:** +```bash +#!/bin/bash +# Find stale "In Progress" issues +jira issue list --jql "\ + status = 'In Progress' AND \ + updated <= -3d AND \ + assignee = currentUser() \ +" --plain + +echo "Reminder: Update status on above issues" +``` + +## Troubleshooting Transitions + +### Issue Won't Transition + +**Problem:** Transition not available + +**Solutions:** +1. Check current status + ```bash + jira issue view PROJ-123 --plain + ``` + +2. View available transitions + ```bash + jira issue move PROJ-123 # Interactive mode shows options + ``` + +3. Check required fields + - Some transitions require fields to be filled + - Use interactive mode to see requirements + +4. Verify permissions + - You may not have permission for certain transitions + - Contact Jira admin if needed + +### Missing Transition + +**Problem:** Expected transition not showing + +**Possible causes:** +- Workflow doesn't include that transition +- Conditional transition based on field values +- Permission restrictions +- Issue type has different workflow + +**Solution:** +```bash +# Check what transitions are available +jira issue move PROJ-123 + +# Ask admin about workflow configuration +``` + +### Stuck in Status + +**Problem:** Issue stuck in a status + +**Solutions:** +1. Check for blockers + ```bash + jira issue view PROJ-123 --plain + ``` + +2. Add comment explaining situation + ```bash + jira issue comment PROJ-123 "Stuck waiting for X. Escalating to Y." + ``` + +3. Link blocking issues + ```bash + jira issue link PROJ-123 PROJ-100 "is blocked by" + ``` + +4. Move to Blocked status + ```bash + jira issue move PROJ-123 "Blocked" --comment "Cannot proceed due to X" + ``` + +### Accidental Transition + +**Problem:** Moved to wrong status + +**Solution:** +```bash +# Move back to correct status +jira issue move PROJ-123 "In Progress" --comment "Moved back to In Progress. Was accidentally marked as Done." +``` + +## Workflow Metrics + +### Cycle Time + +Time from "In Progress" to "Done": +```bash +# Issues completed this week +jira issue list --jql "\ + status = Done AND \ + resolved >= startOfWeek() \ +" --raw +``` + +Calculate: `resolved_date - in_progress_date` + +### Lead Time + +Time from "To Do" to "Done": +```bash +# All resolved issues +jira issue list --jql "resolved >= startOfMonth()" --raw +``` + +Calculate: `resolved_date - created_date` + +### Status Distribution + +```bash +# Count issues by status +jira issue list --status "In Progress" --raw | grep -c key +jira issue list --status "In Review" --raw | grep -c key +jira issue list --status "Done" --raw | grep -c key +``` + +### Blocked Issue Tracking + +```bash +# Currently blocked +jira issue list --status Blocked --plain + +# How long blocked +jira issue list --jql "status = Blocked" --raw +``` + +## Custom Workflows + +Organizations often customize workflows. To understand your workflow: + +1. **View current issue state:** + ```bash + jira issue view PROJ-123 --plain + ``` + +2. **See available transitions:** + ```bash + jira issue move PROJ-123 # Interactive mode + ``` + +3. **Check workflow diagram:** + - Ask Jira admin for workflow documentation + - Or view in Jira UI: Project Settings → Workflows + +4. **Document for team:** + Create a workflow guide specific to your project + +## When to Use This Skill + +- Learning Jira workflow concepts +- Transitioning issues appropriately +- Handling blocked or stuck issues +- Integrating workflows with git/CI/CD +- Troubleshooting transition issues +- Understanding team's specific workflow + +## Best Practices Summary + +1. **Always add meaningful comments** when transitioning +2. **Follow the workflow** - don't skip states +3. **Update issue details** before transitioning +4. **Link related work** (PRs, blockers, etc.) +5. **Use appropriate transitions** for issue type +6. **Verify completion** before marking Done +7. **Handle blockers explicitly** - don't leave hanging +8. **Document custom workflows** for team reference + +## Next Steps + +- Document your team's specific workflows +- Create scripts for common transition patterns +- Set up automation for workflow events +- Define clear Definition of Done for each state +- Establish team norms around transitions