zhongwei/gh-yebot-rad-cc-plugins-plugins-jira-cli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:08:00 +08:00
commit 63eb8220c7
11 changed files with 3971 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
.claude-plugin/plugin.json Normal file
View File

@@ -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"
]
}

3
README.md Normal file
View File

@@ -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

212
agents/jira-manager.md Normal file
View File

@@ -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

429
agents/jira-query-builder.md Normal file
View File

@@ -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
```

337
agents/jira-sprint-master.md Normal file
View File

@@ -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 <SPRINT_ID> 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 <SPRINT_ID> --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 <SPRINT_ID> --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 <SPRINT_ID> 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 <SPRINT_ID> --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 <NEXT_SPRINT_ID> 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.

542
commands/jira-issue-workflow.md Normal file
View File

@@ -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

323
commands/jira-setup.md Normal file
View File

@@ -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.

731
commands/jira-sprint-planning.md Normal file
View File

@@ -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 <SPRINT_ID> --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 <SPRINT_ID> PROJ-123 PROJ-124 PROJ-125
```
**Continue until capacity reached.**
#### Step 4: Assign Initial Ownership
**View sprint issues:**
```bash
jira sprint view <SPRINT_ID> --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 = <SPRINT_ID>" --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 <SPRINT_ID> --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 <SPRINT_ID> 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 <SPRINT_ID> 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 <SPRINT_ID> --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 = <SPRINT_ID>" --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 = <SPRINT_ID>" --raw
# Completed issues
jira issue list --jql "sprint = <SPRINT_ID> AND status = Done" --raw
# Calculate percentage
```
**Story points completed:**
```bash
# Sum story points of completed issues
jira issue list --jql "sprint = <SPRINT_ID> AND status = Done" --raw | grep storyPoints
```
**Issue breakdown:**
```bash
# By type
jira issue list --jql "sprint = <SPRINT_ID>" --plain | grep -c Story
jira issue list --jql "sprint = <SPRINT_ID>" --plain | grep -c Bug
jira issue list --jql "sprint = <SPRINT_ID>" --plain | grep -c Task
```
### Incomplete Work
**Items not finished:**
```bash
jira issue list --jql "sprint = <SPRINT_ID> AND status != Done" --plain
```
**Move to next sprint or backlog:**
```bash
# Move to next sprint
jira sprint add <NEXT_SPRINT_ID> 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 = <SPRINT_ID>" --plain
# Completed work
jira issue list --jql "sprint = <SPRINT_ID> AND status = Done" --plain
# Issues that were blocked
jira issue list --jql "sprint = <SPRINT_ID> 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 = <SPRINT_1> AND status = Done" --raw | grep storyPoints
# Sprint 2
jira issue list --jql "sprint = <SPRINT_2> AND status = Done" --raw | grep storyPoints
# Sprint 3 (current)
jira issue list --jql "sprint = <SPRINT_3> 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 = <SPRINT_ID> 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 = <SPRINT_ID> 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 <SPRINT_1> PROJ-101 PROJ-102
# Sprint 2: Core features
jira sprint add <SPRINT_2> PROJ-103 PROJ-104
# Sprint 3: Polish
jira sprint add <SPRINT_3> 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 <SPRINT_ID> 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 <SPRINT_ID> --plain # Review progress
jira issue list --jql "sprint = <SPRINT_ID> AND status != Done" --plain # Incomplete items
# Move incomplete items
jira sprint add <NEXT_SPRINT_ID> 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 <SPRINT_ID> 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 <SPRINT_ID> --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 <SPRINT_ID> --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

73
plugin.lock.json Normal file
View File

@@ -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": []
}
}

668
skills/jira-jql-patterns/SKILL.md Normal file
View File

@@ -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

636
skills/jira-workflow-transitions/SKILL.md Normal file
View File

@@ -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 <NEXT_SPRINT_ID> 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