tomevault-io Jira Work Orchestration v5.1 (Optimized)
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'];
for (const phase of phases) {
const checkpoint = await sessionStorage.get(`checkpoint:${issueKey}:${phase}`);
if (checkpoint?.canResume) {
return checkpoint; // Resume from most recent valid checkpoint
}
}
return null;
}
Escalation Patterns
STRUGGLE DETECTION & ESCALATION:
═════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────┐
│ LEVEL 1: Agent Self-Recovery (automatic) │
│ ───────────────────────────────────────── │
│ • 3 search attempts with query refinement │
│ • Broaden search pattern on failure │
│ • Try alternative file patterns │
│ • Timeout: 30 seconds total │
└───────────────────────────┬─────────────────────────────────────────┘
│ (if still failing)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ LEVEL 2: Strategy Pivot (automatic) │
│ ───────────────────────────────── │
│ • Switch from Grep to Glob (or vice versa) │
│ • Use Task(Explore) agent for deeper search │
│ • Check registry for known patterns │
│ • Consult project structure cache │
└───────────────────────────┬─────────────────────────────────────────┘
│ (if still failing)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ LEVEL 3: Graceful Degradation (automatic) │
│ ───────────────────────────────────────── │
│ • Proceed with partial context │
│ • Log what's missing for manual review │
│ • Mark result as "low confidence" │
│ • Add TODO comments for missing context │
└───────────────────────────┬─────────────────────────────────────────┘
│ (if critical blocker)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ LEVEL 4: Human Escalation (requires intervention) │
│ ─────────────────────────────────────────────── │
│ • Pause workflow with clear status │
│ • Present what was tried and what failed │
│ • Request specific information needed │
│ • Checkpoint state for resume after input │
└─────────────────────────────────────────────────────────────────────┘
═════════════════════════════════════════════════════════════════════════
Retry Budget & Circuit Breaker
interface RetryBudget {
maxRetries: number;
currentRetries: number;
backoffMs: number[];
circuitOpen: boolean;
lastFailure?: Date;
}
const retryBudgets: Record<string, RetryBudget> = {
jiraApi: { maxRetries: 3, currentRetries: 0, backoffMs: [1000, 2000, 4000], circuitOpen: false },
confluence: { maxRetries: 2, currentRetries: 0, backoffMs: [2000, 5000], circuitOpen: false },
githubApi: { maxRetries: 3, currentRetries: 0, backoffMs: [1000, 2000, 4000], circuitOpen: false },
codeSearch: { maxRetries: 3, currentRetries: 0, backoffMs: [500, 1000, 2000], circuitOpen: false }
};
// Circuit breaker pattern
async function withCircuitBreaker<T>(
service: string,
operation: () => Promise<T>
): Promise<T | null> {
const budget = retryBudgets[service];
// Check if circuit is open (too many recent failures)
if (budget.circuitOpen) {
const timeSinceFailure = Date.now() - (budget.lastFailure?.getTime() || 0);
if (timeSinceFailure < 60000) { // 1 minute cooldown
return null; // Skip this service, use fallback
}
budget.circuitOpen = false; // Reset circuit
}
for (let attempt = 0; attempt < budget.maxRetries; attempt++) {
try {
const result = await operation();
budget.currentRetries = 0; // Reset on success
return result;
} catch (error) {
budget.currentRetries++;
budget.lastFailure = new Date();
if (attempt < budget.maxRetries - 1) {
await sleep(budget.backoffMs[attempt]);
}
}
}
// Open circuit after exhausting retries
budget.circuitOpen = true;
return null;
}
Fallback Strategies
const FALLBACK_STRATEGIES = {
// When Jira API fails
jiraUnavailable: {
action: 'useLocalContext',
steps: [
'Parse issue key from branch name',
'Extract context from commit messages',
'Use cached issue data if available',
'Proceed with minimal context, mark as draft'
]
},
// When Confluence search fails
confluenceUnavailable: {
action: 'skipDocumentation',
steps: [
'Skip Confluence search in EXPLORE',
'Skip doc generation in COMMIT',
'Add TODO for manual documentation',
'Continue with code-only workflow'
]
},
// When codebase search fails
searchFailed: {
action: 'broaden',
steps: [
'Try parent directory',
'Use simpler glob pattern (*.ts instead of **/*.service.ts)',
'Search by keyword instead of path',
'Fall back to git log for file history'
]
},
// When quality gates timeout
gateTimeout: {
action: 'partialCheck',
steps: [
'Run only fast gates (lint, format)',
'Skip slow gates (coverage, complexity)',
'Mark PR as "needs-full-review"',
'Schedule async quality check'
]
}
};
// Apply fallback when primary strategy fails
async function withFallback<T>(
primary: () => Promise<T>,
fallbackKey: keyof typeof FALLBACK_STRATEGIES,
fallbackFn: () => Promise<T>
): Promise<{ result: T; usedFallback: boolean }> {
try {
const result = await withTimeout(primary(), 30000);
return { result, usedFallback: false };
} catch (error) {
console.log(`Primary failed, using fallback: ${fallbackKey}`);
const result = await fallbackFn();
return { result, usedFallback: true };
}
}
Context Budget Enforcement
// Track context usage per phase
class ContextBudgetTracker {
private usage: Map<string, number> = new Map();
private readonly totalBudget = 100000; // tokens
consume(phase: string, tokens: number): boolean {
const current = this.usage.get(phase) || 0;
const phaseBudget = SEARCH_LIMITS.contextBudget[phase];
if (current + tokens > phaseBudget) {
console.warn(`Phase ${phase} exceeding budget: ${current + tokens}/${phaseBudget}`);
return false; // Deny consumption
}
this.usage.set(phase, current + tokens);
return true;
}
getRemaining(): number {
const used = Array.from(this.usage.values()).reduce((a, b) => a + b, 0);
return this.totalBudget - used;
}
shouldCheckpoint(): boolean {
return this.getRemaining() < 25000; // 25% remaining
}
shouldCompress(): boolean {
return this.getRemaining() < 10000; // 10% remaining
}
}
// Enforce budget during agent execution
const budgetTracker = new ContextBudgetTracker();
async function executeWithBudget(phase: string, operation: () => Promise<any>): Promise<any> {
if (budgetTracker.shouldCheckpoint()) {
await checkpointPhase(phase, { partial: true });
}
if (budgetTracker.shouldCompress()) {
await compressContext(); // Summarize and discard old messages
}
const result = await operation();
budgetTracker.consume(phase, estimateTokens(result));
return result;
}
Summary: Mitigation Quick Reference
| Problem | Detection | Mitigation |
|---|---|---|
| Search taking too long | Timeout after 30s | Broaden pattern, try alternatives |
| Same search failing repeatedly | Negative cache hit | Skip with fallback, don't retry |
| Context running out | Budget tracker | Checkpoint + compress |
| API consistently failing | Circuit breaker open | Use cached data or skip |
| Agent stuck in loop | Retry count > 3 | Escalate to human |
| Phase incomplete | Missing artifacts | Resume from checkpoint |
| Low confidence result | Fallback was used | Mark for review, add TODOs |
Subagent Communication Protocol
Message Format
interface AgentMessage {
id: string;
from: string; // Agent identifier
to: string; // Target agent or "orchestrator"
phase: string; // Current workflow phase
type: "result" | "request" | "error" | "status";
payload: any;
timestamp: string;
}
Result Handoff Pattern
// Phase N agent completes and reports
const phaseResult = {
phase: "CODE",
status: "complete",
artifacts: {
filesModified: ["src/api/handler.ts", "src/utils/parser.ts"],
linesAdded: 245,
linesRemoved: 12
},
nextPhaseInput: {
filesToTest: ["src/api/handler.ts"],
coverageTargets: ["handler", "parser"]
}
};
// Orchestrator receives and forwards to Phase N+1
orchestrator.handoff("TEST", phaseResult.nextPhaseInput);
Error Escalation
// Agent encounters blocking error
if (error.severity === "critical") {
return {
type: "error",
escalate: true,
message: "Security vulnerability detected - blocking commit",
requiresHumanReview: true
};
}
Agent Registry (Optimized v5.0)
FAST Mode (3-4 agents)
| Wave | Agent | Model | Purpose |
|---|---|---|---|
| 1 | fast-implementer | haiku | End-to-end: fetch→code→commit |
| 1 | lint-gate | haiku | Quick lint + format (parallel) |
| 2* | fix-agent | sonnet | Only if lint fails |
STANDARD Mode (6-8 agents)
| Wave | Agent | Model | Purpose |
|---|---|---|---|
| 1 | explore-agent | haiku | Codebase analysis |
| 1 | jira-fetch | haiku | Issue context (cached) |
| 1 | confluence-fetch | haiku | Docs search (cached) |
| 2 | plan-code-agent | sonnet | Consolidated plan + implement |
| 3 | lint-format-gate | haiku | Gate Group 1 |
| 3 | security-deps-gate | haiku | Gate Group 2 |
| 3 | coverage-complex-gate | sonnet | Gate Group 3 |
| 4 | commit-pr-agent | sonnet | Commit + PR + Jira link |
FULL Mode (10-12 agents)
| Wave | Agent | Model | Purpose |
|---|---|---|---|
| 1 | deep-explore | sonnet | Comprehensive codebase analysis |
| 1 | jira-full | haiku | Issue + linked issues |
| 1 | confluence-arch | sonnet | Architecture docs, ADRs |
| 1 | security-pre | sonnet | Pre-implementation security review |
| 2 | architect-planner | opus | Detailed implementation plan |
| 2 | test-strategist | sonnet | Test planning and scenarios |
| 3 | code-agent (x2-4) | sonnet | Parallel subtask implementation |
| 4 | gate-group-1 | haiku | Lint + Format |
| 4 | gate-group-2 | haiku | Security + Dependencies |
| 4 | gate-group-3 | sonnet | Coverage + Complexity |
| 4 | deep-security | sonnet | Full SAST analysis |
| 5 | commit-pr-agent | sonnet | Smart commit + comprehensive PR |
| 5 | confluence-doc | sonnet | Generate tech documentation |
Performance Comparison
┌────────────────────────────────────────────────────────────────┐
│ v4.2 vs v5.0 PERFORMANCE COMPARISON │
├────────────────────────────────────────────────────────────────┤
│ │
│ AGENT COUNT REDUCTION │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ v4.2: 13-18 agents (all tasks) │ │
│ │ v5.0: 3-4 (FAST) | 6-8 (STANDARD) | 10-12 (FULL) │ │
│ │ │ │
│ │ Average reduction: 40% fewer agents │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ EXECUTION TIME │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ v4.2 │ v5.0 │ │
│ ├───────────────────────┼────────────────────────────────┤ │
│ │ Simple bug: ~8 min │ FAST: ~2 min (-75%) │ │
│ │ Feature: ~12 min │ STANDARD: ~5 min (-58%) │ │
│ │ Major: ~15 min │ FULL: ~10 min (-33%) │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ GATE CONSOLIDATION │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ v4.2: 5 separate gates (5 agents) │ │
│ │ v5.0: 3 gate groups (3 agents, parallel) │ │
│ │ │ │
│ │ Group 1: Static Analysis + Formatting │ │
│ │ Group 2: Security Scanner + Dependency Health │ │
│ │ Group 3: Test Coverage + Complexity Analyzer │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ CACHING BENEFITS │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Same issue re-run: 50% faster │ │
│ │ Same session/project: 30% faster │ │
│ │ Unchanged files: Skip redundant analysis │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ COST REDUCTION (API calls) │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ FAST mode: ~70% fewer API calls │ │
│ │ STANDARD mode: ~45% fewer API calls │ │
│ │ haiku preference: Lower cost per agent │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────┘
Total Agents per Run (v5.0):
- FAST: 3-4 agents
- STANDARD: 6-8 agents
- FULL: 10-12 agents
v4.2 Comparison: Was 13-18 agents for ALL task types
Jira Integration
This command automatically:
- Transitions issue to "In Progress"
- Adds progress comments
- Logs work time
- Creates smart commits
- Links PRs to issues
Confluence Integration (Advanced)
The workflow integrates with Confluence for documentation:
Auto-Generated Documentation
// After successful commit, generate Confluence page
Task({
subagent_type: "general-purpose",
model: "sonnet",
prompt: `Create Confluence documentation for ${issueKey}:
1. Generate technical design document
2. Document API changes (if any)
3. Create/update runbook entries
4. Add architecture diagrams (mermaid)
Use mcp__MCP_DOCKER__confluence_create_page`
});
Confluence Features Used
| Feature | Purpose | Trigger |
|---|---|---|
| Page Creation | Auto-create tech docs | After COMMIT phase |
| Page Update | Update existing docs | If page exists |
| Search | Find related docs in EXPLORE | mcp__MCP_DOCKER__confluence_search |
| Attachment | Quality reports, diagrams | After QUALITY phase |
| Labels | Categorize documentation | Auto-tagged |
| Macro Insertion | Jira issue embed, code blocks | Tech docs |
Documentation Templates
// Technical Design Document Template
const techDocTemplate = {
title: `[${issueKey}] Technical Design -
…(truncated)