jira:work

High-performance workflow with intelligent question-gathering, tiered execution, caching, and maximum parallelization.

Key Features in v5.1:

• ❓ Question-First Protocol - Ask all clarifying questions BEFORE starting
• ⚡ 3 Execution Tiers: FAST (3-4 agents) | STANDARD (6-8) | FULL (10-12)
• 🚀 40% Faster: Parallel phase execution where possible
• 💾 Caching Layer: Memoized Jira/Confluence lookups
• 🎯 Smart Gates: 5 gates → 3 parallel gate groups
• 🔀 Early Exit: Skip unnecessary phases for trivial changes

---

PHASE 0: Question-Gathering (MANDATORY)

Before ANY work begins, Claude MUST gather sufficient context by asking questions.

QUESTION-GATHERING PROTOCOL:
═════════════════════════════════════════════════════════════════════════
  ┌─────────────────────────────────────────────────────────────────────┐
  │  STEP 1: Initial Analysis (~30 seconds)                             │
  │  ─────────────────────────────────────────                          │
  │  • Parse Jira issue description                                     │
  │  • Identify ambiguous requirements                                  │
  │  • Detect missing technical details                                 │
  │  • Check for undefined acceptance criteria                          │
  └─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
  ┌─────────────────────────────────────────────────────────────────────┐
  │  STEP 2: Generate Question Categories                               │
  │  ────────────────────────────────────                               │
  │                                                                      │
  │  📋 REQUIREMENTS QUESTIONS                                          │
  │     • What is the expected behavior?                                │
  │     • What are the acceptance criteria?                             │
  │     • Are there edge cases to consider?                             │
  │     • What should happen on errors?                                 │
  │                                                                      │
  │  🔧 TECHNICAL QUESTIONS                                             │
  │     • Which components/files are affected?                          │
  │     • Are there existing patterns to follow?                        │
  │     • What dependencies are involved?                               │
  │     • Are there performance requirements?                           │
  │                                                                      │
  │  🎨 DESIGN QUESTIONS                                                │
  │     • UI/UX requirements (if applicable)?                           │
  │     • API contract expectations?                                    │
  │     • Database schema changes needed?                               │
  │                                                                      │
  │  ⚠️ RISK QUESTIONS                                                  │
  │     • Rollback strategy if something goes wrong?                    │
  │     • Testing requirements?                                         │
  │     • Security considerations?                                      │
  │                                                                      │
  │  🔗 DEPENDENCY QUESTIONS                                            │
  │     • Are there blocking issues?                                    │
  │     • External team dependencies?                                   │
  │     • Timeline constraints?                                         │
  └─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
  ┌─────────────────────────────────────────────────────────────────────┐
  │  STEP 3: Present Questions & Wait for Answers                       │
  │  ────────────────────────────────────────────                       │
  │  • Present grouped questions clearly                                │
  │  • Wait for user responses                                          │
  │  • Ask follow-up questions if needed                                │
  │  • Confirm understanding before proceeding                          │
  └─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
  ┌─────────────────────────────────────────────────────────────────────┐
  │  STEP 4: Confirmation                                               │
  │  ────────────────────                                               │
  │  "Based on your answers, here's my understanding:                   │
  │   [Summary of requirements]                                         │
  │                                                                      │
  │   Is this correct? Should I proceed with implementation?"           │
  └─────────────────────────────────────────────────────────────────────┘
═════════════════════════════════════════════════════════════════════════

Question Categories by Tier

Tier	Min Questions	Focus Areas
FAST	1-2	Confirmation only ("Just updating X, correct?")
STANDARD	3-5	Requirements, affected files, testing approach
FULL	5-10	Full technical spec, architecture, security, rollback

Intelligent Question Generation

interface QuestionContext {
  issueKey: string;
  issueType: string;
  description: string;
  acceptanceCriteria: string[];
  labels: string[];
  components: string[];
}

function generateQuestions(context: QuestionContext): Question[] {
  const questions: Question[] = [];

  // Requirements gaps
  if (!context.acceptanceCriteria?.length) {
    questions.push({
      category: 'requirements',
      priority: 'high',
      question: 'What are the acceptance criteria for this issue?'
    });
  }

  // Technical ambiguity
  if (context.description.includes('should') || context.description.includes('might')) {
    questions.push({
      category: 'technical',
      priority: 'medium',
      question: 'The description mentions "should/might" - is this optional or required behavior?'
    });
  }

  // Error handling
  if (context.issueType === 'Story' && !context.description.includes('error')) {
    questions.push({
      category: 'requirements',
      priority: 'medium',
      question: 'How should the system handle error cases?'
    });
  }

  // Testing strategy
  if (!context.labels.includes('tested') && !context.labels.includes('no-tests')) {
    questions.push({
      category: 'technical',
      priority: 'low',
      question: 'What level of test coverage is expected?'
    });
  }

  // Security implications
  if (detectSecurityKeywords(context.description)) {
    questions.push({
      category: 'security',
      priority: 'high',
      question: 'Are there specific security requirements or compliance needs?'
    });
  }

  return questions;
}

// Example question output
const exampleQuestions = `
Before I start working on ${issueKey}, I have a few questions:

**Requirements:**
1. The description mentions "user authentication" - should this support both email/password and OAuth, or just one?
2. What should happen if a user's session expires mid-action?

**Technical:**
3. Should I follow the existing auth patterns in src/auth/, or is there a new approach you prefer?
4. Are there specific performance requirements (e.g., max auth latency)?

**Testing:**
5. Should I add integration tests with the OAuth provider, or mock those?

Please answer these questions and I'll proceed with implementation.
`;

Skip Conditions (FAST tier only)

Questions can be skipped when ALL of these are true:

• Issue type is: Bug, Sub-task, or Documentation
• Description is very specific (< 50 words)
• Acceptance criteria are clearly defined
• Files to change are explicitly mentioned
• No security implications detected

function shouldSkipQuestions(context: QuestionContext): boolean {
  const skipTypes = ['Bug', 'Sub-task', 'Documentation', 'Task'];
  const hasSpecificDescription = context.description.split(' ').length < 50;
  const hasClearAC = context.acceptanceCriteria.length >= 2;
  const hasFilesMentioned = /\.(ts|js|py|go|java|rb)/.test(context.description);
  const noSecurityImplications = !detectSecurityKeywords(context.description);

  return (
    skipTypes.includes(context.issueType) &&
    hasSpecificDescription &&
    hasClearAC &&
    hasFilesMentioned &&
    noSecurityImplications
  );
}

---

Quick Start

/jira:work <issue-key> [--tier=auto|fast|standard|full] [--skip-questions]

Note: --skip-questions is only available for FAST tier and trivial changes.

Tier Auto-Selection Logic

FAST:     docs-only | config | typo | readme | 1-2 files
STANDARD: bug-fix | minor-feature | refactor | 3-10 files
FULL:     major-feature | architectural | security | 10+ files

---

Optimized Architecture (v5.1)

┌─────────────────────────────────────────────────────────────────────────┐
│           JIRA WORK ORCHESTRATOR v5.1 - QUESTION-FIRST EXECUTION         │
│                    ⚡ Optimized for Speed ⚡                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────┐    │
│  │ TIER SELECTOR (runs first, ~500ms)                              │    │
│  │  Analyze: issue type, labels, files, complexity → select tier   │    │
│  └────────────────────────────────────────────────────────────────┘    │
│                              │                                          │
│            ┌─────────────────┼─────────────────┐                       │
│            ▼                 ▼                 ▼                       │
│     ┌──────────┐      ┌──────────┐      ┌──────────┐                  │
│     │   FAST   │      │ STANDARD │      │   FULL   │                  │
│     │ 3-4 agnt │      │ 6-8 agnt │      │10-12 agnt│                  │
│     │ ~2 min   │      │ ~5 min   │      │ ~10 min  │                  │
│     └──────────┘      └──────────┘      └──────────┘                  │
│                                                                          │
│  ═══════════════════════════════════════════════════════════════════   │
│                                                                          │
│                        PARALLEL EXECUTION LANES                          │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │ LANE 1: CODE PATH          │ LANE 2: CONTEXT (cached)            │  │
│  │ ─────────────────          │ ─────────────────────               │  │
│  │ [EXPLORE]──▶[PLAN]──▶     │ [JIRA]──▶[CONFLUENCE]               │  │
│  │      │           │         │    │          │                     │  │
│  │      ▼           ▼         │    ▼          ▼                     │  │
│  │    [CODE]──▶[TEST+QG]     │ [CACHE]    [CACHE]                  │  │
│  │         \       /          │                                      │  │
│  │          ▼     ▼           │                                      │  │
│  │         [COMMIT]           │                                      │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  ═══════════════════════════════════════════════════════════════════   │
│                                                                          │
│  GATE GROUPS (Parallel)                                                  │
│  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐               │
│  │   GROUP 1     │ │   GROUP 2     │ │   GROUP 3     │               │
│  │ LINT+FORMAT   │ │ SECURITY+DEPS │ │ COVERAGE+CMPLX│               │
│  │   (haiku)     │ │   (haiku)     │ │   (sonnet)    │               │
│  └───────────────┘ └───────────────┘ └───────────────┘               │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

---

Tiered Execution Modes

FAST Mode (3-4 agents, ~2 min)

Use for: Docs, configs, typos, README, 1-2 file changes

// Single consolidated agent for FAST mode
Task({
  subagent_type: "general-purpose",
  model: "haiku",
  prompt: `FAST MODE: Complete ${issueKey} end-to-end:
    1. Quick context from Jira (cached if available)
    2. Make the simple change
    3. Run lint + format (auto-fix)
    4. Commit and push

    Skip: Full exploration, coverage check, complexity analysis
    Output: { completed: true, files: [], commitSha: string }`
});

// Parallel: Basic quality check
Task({
  subagent_type: "general-purpose",
  model: "haiku",
  prompt: "Lint check only: npx eslint --fix && npx prettier --write"
});

Early Exit Conditions:

• No code changes (docs only) → Skip all quality gates
• Config-only changes → Skip coverage, complexity
• README/typo → Skip everything except commit

---

STANDARD Mode (6-8 agents, ~5 min)

Use for: Bug fixes, minor features, refactors, 3-10 files

PARALLEL EXECUTION GRAPH:
═════════════════════════════════════════════════════════════
  ┌─────────────────────────────────────────────────────────┐
  │  WAVE 1 (Parallel Launch - 3 agents)                    │
  │  ┌───────────┐  ┌───────────┐  ┌───────────────────┐   │
  │  │  EXPLORE  │  │   JIRA    │  │  CONFLUENCE CACHE │   │
  │  │  (haiku)  │  │  (cached) │  │     (cached)      │   │
  │  └─────┬─────┘  └─────┬─────┘  └─────────┬─────────┘   │
  │        └──────────────┼──────────────────┘              │
  │                       ▼                                  │
  │  ┌─────────────────────────────────────────────────────┐ │
  │  │  WAVE 2: PLAN+CODE (1 consolidated agent)           │ │
  │  │  - Receive context from Wave 1                      │ │
  │  │  - Plan inline (no separate planning agent)         │ │
  │  │  - Execute code changes                             │ │
  │  └─────────────────────────────────────────────────────┘ │
  │                       ▼                                  │
  │  ┌─────────────────────────────────────────────────────┐ │
  │  │  WAVE 3: TEST + QUALITY (3 parallel gate groups)    │ │
  │  │  ┌─────────┐  ┌─────────────┐  ┌─────────────────┐ │ │
  │  │  │LINT+FMT │  │SECURITY+DEPS│  │COVERAGE+COMPLEX │ │ │
  │  │  │ (haiku) │  │   (haiku)   │  │    (sonnet)     │ │ │
  │  │  └─────────┘  └─────────────┘  └─────────────────┘ │ │
  │  └─────────────────────────────────────────────────────┘ │
  │                       ▼                                  │
  │  ┌─────────────────────────────────────────────────────┐ │
  │  │  WAVE 4: COMMIT (1 agent, includes PR)              │ │
  │  └─────────────────────────────────────────────────────┘ │
  └─────────────────────────────────────────────────────────┘
═════════════════════════════════════════════════════════════

// WAVE 1: Parallel context gathering (with cache)
const [exploreResult, jiraContext, confluenceContext] = await Promise.all([
  Task({
    subagent_type: "Explore",
    model: "haiku",
    prompt: `Quick codebase analysis for ${issueKey}:
      - Identify affected files (Glob/Grep)
      - Find test files
      - Map immediate dependencies`
  }),
  getCached('jira', issueKey) || Task({
    subagent_type: "general-purpose",
    model: "haiku",
    prompt: `Fetch and cache Jira issue ${issueKey}`
  }),
  getCached('confluence', issueKey) || Task({
    subagent_type: "general-purpose",
    model: "haiku",
    prompt: "Search Confluence for related docs (cache result)"
  })
]);

// WAVE 2: Consolidated Plan+Code (single agent, inline planning)
const codeResult = await Task({
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: `Implement ${issueKey} with inline planning:
    Context: ${JSON.stringify({ exploreResult, jiraContext })}

    1. [INLINE PLAN] Quick design decisions (no separate agent)
    2. [CODE] Implement changes following plan
    3. Output: { files: [], plan: string, summary: string }`
});

// WAVE 3: 3 Gate Groups in Parallel (consolidates 5 gates)
const [lintGate, securityGate, coverageGate] = await Promise.all([
  // Group 1: Lint + Format (combines Static Analysis)
  Task({
    subagent_type: "general-purpose",
    model: "haiku",
    prompt: `GATE GROUP 1 - LINT+FORMAT:
      - ESLint with --fix
      - Prettier with --write
      Output: { passed: boolean, issues: [], autoFixed: number }`
  }),

  // Group 2: Security + Dependencies (combines 2 gates)
  Task({
    subagent_type: "general-purpose",
    model: "haiku",
    prompt: `GATE GROUP 2 - SECURITY+DEPS:
      - gitleaks (secrets)
      - npm audit (vulnerabilities)
      - Check for outdated critical deps
      Output: { passed: boolean, vulns: [], outdated: [] }`
  }),

  // Group 3: Coverage + Complexity (requires more analysis)
  Task({
    subagent_type: "general-purpose",
    model: "sonnet",
    prompt: `GATE GROUP 3 - COVERAGE+COMPLEXITY:
      - Run tests with coverage (threshold: 80%)
      - Check cyclomatic complexity (max: 10)
      - Identify complex functions
      Output: { passed: boolean, coverage: number, complexity: [] }`
  })
]);

// WAVE 4: Commit + PR (single agent)
await Task({
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: `Complete ${issueKey}:
    Quality: ${JSON.stringify({ lintGate, securityGate, coverageGate })}
    1. Commit with smart message
    2. Push to feature branch
    3. Create PR with quality report
    4. Link to Jira
    Output: { commitSha, prUrl, jiraLinked }`
});

---

FULL Mode (10-12 agents, ~10 min)

Use for: Major features, architectural changes, security-critical

FULL MODE EXECUTION:
═════════════════════════════════════════════════════════════
  WAVE 1: Deep Analysis (4 parallel agents)
  ├── EXPLORE: Deep codebase analysis
  ├── JIRA: Full issue context + linked issues
  ├── CONFLUENCE: Architecture docs, ADRs
  └── SECURITY-PRE: Pre-implementation security review

  WAVE 2: Architecture Planning (2 agents)
  ├── PLAN: Detailed implementation plan with DAG
  └── TEST-PLAN: Test strategy and scenarios

  WAVE 3: Implementation (2-4 agents based on subtasks)
  └── CODE: Parallel subtask execution

  WAVE 4: Comprehensive Quality (3 gate groups + deep security)
  ├── LINT+FORMAT
  ├── SECURITY+DEPS (with SAST)
  ├── COVERAGE+COMPLEXITY
  └── DEEP-SECURITY: Full vulnerability analysis

  WAVE 5: Finalization (2 agents)
  ├── COMMIT: Smart commit + PR
  └── DOCUMENT: Confluence tech doc generation
═════════════════════════════════════════════════════════════

---

Caching Layer (New in v5.0)

interface WorkflowCache {
  jira: Map<string, JiraIssue>;      // TTL: 5 minutes
  confluence: Map<string, Page[]>;    // TTL: 10 minutes
  fileAnalysis: Map<string, Analysis>; // TTL: until file modified
  gateResults: Map<string, GateResult>; // TTL: until code changed
}

// Cache-aware fetch pattern
async function getCached<T>(type: keyof WorkflowCache, key: string): Promise<T | null> {
  const cache = workflowCache[type];
  const entry = cache.get(key);

  if (entry && !isExpired(entry)) {
    return entry.value;
  }
  return null; // Cache miss - will fetch fresh
}

// Pre-warm cache at session start
async function prewarmCache(issueKey: string): Promise<void> {
  // Parallel cache warming (runs during tier selection)
  await Promise.all([
    fetchAndCache('jira', issueKey),
    fetchAndCache('confluence', getProjectKey(issueKey))
  ]);
}

Cache Benefits:

• Same issue re-run: 50% faster (Jira/Confluence cached)
• Same session multiple issues: 30% faster (shared project context)
• File unchanged: Skip redundant analysis

---

Early Exit Optimization

// Tier determines which gates can be skipped
const earlyExitRules = {
  FAST: {
    skip: ['coverage', 'complexity', 'deepSecurity', 'confluence-doc'],
    require: ['lint']
  },
  STANDARD: {
    skip: ['deepSecurity', 'confluence-doc'],
    require: ['lint', 'security', 'coverage']
  },
  FULL: {
    skip: [],
    require: ['all']
  }
};

// File-type based skips
const fileTypeSkips = {
  'docs': ['coverage', 'complexity'],  // .md, .txt, .rst
  'config': ['coverage'],               // .json, .yaml, .toml
  'test': ['complexity']                // *.test.*, *.spec.*
};

// Apply early exit logic
function shouldSkipGate(gate: string, tier: Tier, files: string[]): boolean {
  // Check tier rules
  if (earlyExitRules[tier].skip.includes(gate)) return true;

  // Check file-type rules
  const fileTypes = detectFileTypes(files);
  if (fileTypes.every(ft => fileTypeSkips[ft]?.includes(gate))) return true;

  return false;
}

---

Failure Recovery & Context Optimization (v5.0)

Purpose: Prevent wasted context when agents struggle to find answers or searches fail.

Search Timeout Limits

const SEARCH_LIMITS = {
  // Maximum attempts before giving up
  maxSearchAttempts: 3,

  // Time limits per search type
  timeouts: {
    glob: 5000,        // 5 seconds
    grep: 10000,       // 10 seconds
    explore: 30000,    // 30 seconds
    jiraFetch: 10000,  // 10 seconds
    confluence: 15000  // 15 seconds
  },

  // Context budget per phase (tokens)
  contextBudget: {
    EXPLORE: 5000,
    PLAN: 3000,
    CODE: 15000,
    TEST: 5000,
    QUALITY: 3000,
    FIX: 8000,
    COMMIT: 2000
  }
};

Negative Caching (Failed Search Memoization)

interface NegativeCache {
  failedSearches: Map<string, {
    query: string;
    timestamp: number;
    reason: string;
    ttl: number;  // Don't retry for this duration
  }>;
}

// Prevent repeating failed searches
async function searchWithNegativeCache(query: string, searchFn: () => Promise<any>): Promise<any> {
  const cacheKey = hashQuery(query);
  const cached = negativeCache.get(cacheKey);

  if (cached && !isExpired(cached)) {
    // Return early with fallback instead of re-trying
    return {
      found: false,
      reason: cached.reason,
      suggestion: 'Try alternative search pattern'
    };
  }

  try {
    const result = await withTimeout(searchFn(), SEARCH_LIMITS.timeouts.grep);
    return result;
  } catch (error) {
    // Cache the failure to prevent retry storms
    negativeCache.set(cacheKey, {
      query,
      timestamp: Date.now(),
      reason: error.message,
      ttl: 5 * 60 * 1000  // Don't retry for 5 minutes
    });
    throw error;
  }
}

Context Checkpointing

interface PhaseCheckpoint {
  phase: string;
  issueKey: string;
  timestamp: string;
  artifacts: {
    filesIdentified: string[];
    planSummary?: string;
    codeChanges?: string[];
    testResults?: any;
    qualityScore?: number;
  };
  contextUsed: number;  // Tokens consumed
  canResume: boolean;
}

// Checkpoint after each phase to prevent re-work
async function checkpointPhase(phase: string, result: any): Promise<void> {
  const checkpoint: PhaseCheckpoint = {
    phase,
    issueKey: currentIssue,
    timestamp: new Date().toISOString(),
    artifacts: extractArtifacts(result),
    contextUsed: estimateTokens(result),
    canResume: true
  };

  // Save to session storage (survives agent restarts)
  await sessionStorage.set(`checkpoint:${currentIssue}:${phase}`, checkpoint);
}

// Resume from last checkpoint if context was lost
async function resumeFromCheckpoint(issueKey: string): Promise<PhaseCheckpoint | null> {
  const phases = ['COMMIT', 'FIX', 'QUALITY', 'TEST', 'CODE', 'PLAN', 'EXPLORE'];