Initial commit

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

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.

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