JIRA Workflow Agent - Usage Guide

Complete guide for using the JIRA Workflow Agent skill.

Quick Start

Prerequisites

JIRA Credentials - Configure in ~/.env:

JIRA_BASE_URL=https://sonatus.atlassian.net/
JIRA_EMAIL=your.email@sonatus.com
JIRA_API_TOKEN=your_api_token_here

GitHub CLI - Authenticated and ready:
```
gh auth status
```
Git Repository - Initialized with remote configured

Basic Usage

Simply provide a JIRA ticket URL or ID:

https://sonatus.atlassian.net/browse/CCU2-17741

Or:

CCU2-17741

The agent will automatically:

✅ Analyze the ticket
⚠️ [Approval 1] Ask for implementation approval
✅ Implement code changes
✅ Run build & tests
⚠️ [Approval 2] Ask for PR approval
✅ Create pull request

Workflow Modes

Mode 1: ANALYZE (Automatic)

Purpose: Analyze JIRA ticket and generate execution plan

Example Request:

Analyze this JIRA ticket: CCU2-17741

Output:

## 📋 Execution Plan

**JIRA**: CCU2-17741 - Add config parameter for daemon startup
**Work Type**: Feature
**Priority**: High
**Complexity**: Medium

### Affected Files:
- src/daemon/main.cpp
- include/config.h

### Acceptance Criteria:
- [ ] Parameter configurable via config file
- [ ] Invalid values rejected
- [ ] Applied on daemon startup

### Estimated Effort: 15-20 minutes

Mode 2: IMPLEMENT (Approval Required ⚠️)

Purpose: Create feature branch and implement code

Approval Checkpoint 1:

## 🔍 Implementation Plan Review

**Proceed with code implementation?**
- approve - Continue
- modify - Adjust plan
- reject - Abort

User Response: approve

Actions:

Creates feature branch: CCU2-17741-add-config-parameter
Implements code changes based on plan
Updates affected files

Mode 3: VERIFY (Automatic)

Purpose: Run build and tests

Output:

## ✅ Verification Report

- ✅ Build: PASSED (0 errors, 0 warnings)
- ✅ Tests: PASSED (15/15 tests)
- ✅ MISRA: PASSED (0 violations)
- ✅ Quality: Grade A

Ready for submission.

Mode 4: SUBMIT (Approval Required ⚠️)

Purpose: Create commit and pull request

Approval Checkpoint 2:

## 📤 Pull Request Review

**Verification Results**:
- ✅ All checks passed

**Create pull request?**
- approve - Create PR
- modify - Edit details
- reject - Commit only

User Response: approve

Actions:

Creates commit using /jira-commit
Creates PR using /jira-pr
Links JIRA ticket

Mode 5: COMPLETE (Orchestrator)

Purpose: Execute full pipeline end-to-end

Example Request:

Complete workflow for CCU2-17741

Process:

ANALYZE → IMPLEMENT (approval) → VERIFY → SUBMIT (approval) → COMPLETE

Usage Scenarios

Scenario 1: Full Automation

User Request:

Implement this JIRA ticket: https://sonatus.atlassian.net/browse/CCU2-17741

Agent Actions:

Analyzes ticket
Shows implementation plan → [User approves]
Implements code
Runs verification
Shows PR details → [User approves]
Creates PR

Result: PR created and ready for review

Scenario 2: Analysis Only

User Request:

Analyze CCU2-17741 and create a plan

Agent Actions:

Fetches ticket data
Classifies work type
Generates execution plan
Shows checklist

Result: Implementation plan for manual execution

Scenario 3: Resume from Interruption

User Request (after session restart):

Continue working on CCU2-17741

Agent Actions:

Lists memories: list_memories()
Finds existing plan: plan_CCU2-17741
Checks last completed phase
Asks: "Resume from [last phase]?"
[User confirms]
Continues workflow

Result: Seamless continuation from where you left off

Scenario 4: Build/Test Only

User Request:

Run verification for CCU2-17741

Agent Actions:

Detects build system
Runs build
Runs tests
Runs static analysis
Generates report

Result: Verification report without code changes

Approval Checkpoints

Checkpoint 1: Before Implementation

When: After analysis, before code changes

You Can:

✅ Approve: Proceed with implementation
🔧 Modify: Adjust files, approach, or criteria
❌ Reject: Abort workflow

Modification Options:

What would you like to change?
- files - Adjust affected files list
- approach - Change implementation approach
- criteria - Update acceptance criteria

Checkpoint 2: Before PR Creation

When: After verification, before PR

You Can:

✅ Approve: Create PR now
🔧 Modify: Edit PR title, description, reviewers
❌ Reject: Keep commits only (no PR)

Modification Options:

What would you like to change?
- title - Edit PR title
- description - Edit PR description
- reviewers - Add/change reviewers
- labels - Add/change labels

Error Handling

Build Failure

Error:

❌ Build failed with 3 errors

Recovery Options:

fix - Fix manually and retry
rollback - Undo changes
abort - Stop workflow

Test Failure

Error:

❌ Tests Failed (3/15 failed)

Recovery Options:

fix - Investigate and fix
rollback - Undo changes
abort - Stop workflow

JIRA API Error

Error:

❌ JIRA API timeout

Recovery:

Automatic retry (3 attempts with exponential backoff)
If fails: Manual ticket ID entry

Rollback Levels

Level 1: Soft Rollback

git reset --hard HEAD

Reverts uncommitted changes
Preserves branch and commits

Level 2: Branch Rollback

git checkout master
git branch -D CCU2-17741-*

Deletes feature branch
Returns to base branch

Level 3: Memory Rollback

Clears workflow memories
Preserves code changes

Level 4: Complete Rollback

Deletes everything (branch + memories)
Full reset

Advanced Features

Cross-Session Persistence

Automatic State Saving:

Every 30 minutes: checkpoint_{timestamp}_{ticket_id}
After each phase: phase_{N}_{mode}_{ticket_id}
After approvals: checkpoint_{1|2}_{ticket_id}

Resume Workflow:

Continue CCU2-17741

Agent will:

Load last checkpoint
Show progress so far
Ask to continue
Resume from last phase

Memory Management

View Progress:

Show me the status of CCU2-17741

Clear Memories (after completion):

Cleanup CCU2-17741 workflow

Custom Commit Messages

Override Default:

Use custom commit message for CCU2-17741:
"feat: add configurable startup delay with validation"

Custom PR Details

Override Default:

Create PR for CCU2-17741 with custom title:
"[CCU2-17741] Implement configurable daemon startup delay"

Best Practices

1. Clear JIRA Tickets

Ensure your JIRA ticket has:

✅ Clear summary
✅ Detailed description
✅ Acceptance criteria listed
✅ Affected components tagged

2. Clean Git State

Before starting:

git status  # No uncommitted changes
git branch  # On main/master

3. Review Approvals Carefully

At each checkpoint:

Read the plan/details thoroughly
Verify files and approach
Modify if needed before approving

4. Monitor Verification

Check build/test output:

Address failures immediately
Don't skip quality checks
Use rollback if needed

5. Keep Sessions Active

For long workflows:

Stay engaged during execution
Respond to prompts promptly
Resume if interrupted

Troubleshooting

Skill Not Activating

Symptoms: Agent doesn't recognize JIRA workflow request

Solutions:

Use explicit trigger words:
- "JIRA workflow"
- "ticket automation"
- "implement JIRA ticket"
Provide full JIRA URL:
- https://sonatus.atlassian.net/browse/CCU2-17741

Check skill is enabled:

ls ~/.claude-config/projects/container-manager/skills/

JIRA Authentication Failing

Symptoms: "401 Unauthorized" or "403 Forbidden"

Solutions:

Check ~/.env:
```
cat ~/.env | grep JIRA
```
Regenerate API token:
- Visit: https://id.atlassian.com/manage-profile/security/api-tokens
- Create new token
- Update ~/.env
Verify email matches JIRA account

Build System Not Detected

Symptoms: "No supported build system detected"

Solutions:

Ensure build files exist:
- CMake: CMakeLists.txt
- Yocto: bitbake.conf or poky/
- npm: package.json
- Cargo: Cargo.toml
- Make: Makefile
Run from project root:
```
cd /path/to/container-manager
```

PR Creation Fails

Symptoms: "gh: command not found" or "not authenticated"

Solutions:

Install GitHub CLI:
```
brew install gh  # macOS
```
Authenticate:
```
gh auth login
```
Verify authentication:
```
gh auth status
```

Examples

Example 1: Simple Feature Implementation

Request:

Implement CCU2-17741

Workflow:

Agent analyzes ticket
Shows plan with 3 files to modify
[You approve]
Agent implements code
Build passes, tests pass
Agent shows PR details
[You approve]
PR created: https://github.com/org/repo/pull/123

Duration: ~15-20 minutes

Example 2: Complex Feature with Adjustments

Request:

Complete workflow for CCU2-18500

Workflow:

Agent analyzes complex ticket
Shows plan with 8 files across 3 components
[You modify: remove 2 files, adjust approach]
Agent updates plan
[You approve modified plan]
Agent implements code
Build passes, but 2 tests fail
Agent shows failures
[You choose: fix manually]
You fix tests
[You run: "retry verification for CCU2-18500"]
All tests pass
Agent shows PR details
[You approve]
PR created

Duration: ~1-2 hours

Example 3: Analysis Only (Planning)

Request:

Analyze CCU2-19000 and create implementation plan

Workflow:

Agent fetches ticket
Analyzes requirements
Generates detailed plan:
- Work type: Refactoring
- Complexity: High
- 12 files affected
- 5 acceptance criteria
- Estimated: 2-3 hours
Creates TodoWrite checklist
Saves to memory
Shows plan

Result: You have a complete plan to execute manually or later

Testing Checklist

Use this checklist when testing the skill:

Pre-Test Setup

JIRA credentials configured in ~/.env
GitHub CLI authenticated (gh auth status)
Git repository clean (git status)
On main/master branch (git branch)

Test 1: Simple Feature

Test 2: Modification Flow

Test 3: Error Recovery

Test 4: Session Resume

Test 5: Memory Persistence

FAQ

Q: Can I use this for non-CCU2 tickets? A: Yes, it supports CCU2, SEB, and CRM projects.

Q: What if my ticket doesn't have acceptance criteria? A: The agent will generate a plan based on description and summary.

Q: Can I skip the approval checkpoints? A: Not recommended. Semi-auto mode requires 2 approvals for safety.

Q: What happens if I reject at checkpoint 1? A: Workflow stops, branch is optionally deleted, no code changes made.

Q: Can I modify the plan after approval? A: Yes, use "modify" option at approval checkpoint.

Q: How do I resume an interrupted workflow? A: Just say "Continue working on CCU2-XXXXX"

Q: Can I run only build/test without implementation? A: Yes, request "Verify CCU2-XXXXX" or use Mode 3 directly.

Q: What if tests fail? A: You can fix manually and retry, or rollback changes.

Q: Is the skill language-specific? A: No, it works with any project (C/C++, Python, JS, etc.)

Q: Can I customize commit messages? A: Yes, either through modification at checkpoint or by providing custom message.

Version History

v1.0.0 (2026-01-07)
- Initial release
- 5-mode workflow (ANALYZE, IMPLEMENT, VERIFY, SUBMIT, COMPLETE)
- Semi-auto with 2 approval checkpoints
- TodoWrite + Serena memory integration
- Error recovery with 4 rollback levels
- Cross-session resume capability
- Integration with /jira-commit and /jira-pr

Support

For issues or questions:

Check this README
Review reference documentation in references/
Check JIRA integration script: ~/.claude-config/projects/container-manager/scripts/jira-integration.sh
Contact CCU2 team

Reference Documentation

Detailed technical documentation:

skill.md - Main skill definition and mode overview
references/jira-analysis.md - JIRA API patterns and ticket parsing
references/workflow-modes.md - Complete mode implementation logic
references/approval-checkpoints.md - Approval UI/UX and handling
references/memory-schema.md - Serena memory structure and TodoWrite integration
references/error-recovery.md - Error handling and rollback mechanisms
references/integration-commands.md - /jira-commit and /jira-pr integration

jira-workflow-agent

JIRA Workflow Agent - Usage Guide

Quick Start

Prerequisites

Basic Usage

Workflow Modes

Mode 1: ANALYZE (Automatic)

Mode 2: IMPLEMENT (Approval Required ⚠️)

Mode 3: VERIFY (Automatic)

Mode 4: SUBMIT (Approval Required ⚠️)

Mode 5: COMPLETE (Orchestrator)

Usage Scenarios

Scenario 1: Full Automation

Scenario 2: Analysis Only

Scenario 3: Resume from Interruption

Scenario 4: Build/Test Only

Approval Checkpoints

Checkpoint 1: Before Implementation

Checkpoint 2: Before PR Creation

Error Handling

Build Failure

Test Failure

JIRA API Error

Rollback Levels

Level 1: Soft Rollback

Level 2: Branch Rollback

Level 3: Memory Rollback

Level 4: Complete Rollback

Advanced Features

Cross-Session Persistence

Memory Management

Custom Commit Messages

Custom PR Details

Best Practices

1. Clear JIRA Tickets

2. Clean Git State

3. Review Approvals Carefully

4. Monitor Verification

5. Keep Sessions Active

Troubleshooting

Skill Not Activating

JIRA Authentication Failing

Build System Not Detected

PR Creation Fails

Examples

Example 1: Simple Feature Implementation

Example 2: Complex Feature with Adjustments

Example 3: Analysis Only (Planning)

Testing Checklist

Pre-Test Setup

Test 1: Simple Feature

Test 2: Modification Flow

Test 3: Error Recovery

Test 4: Session Resume

Test 5: Memory Persistence

FAQ

Version History

Support

Reference Documentation