@doingdev/opencode-claude-manager-plugin 0.1.56 → 0.1.57

package/dist/manager/team-orchestrator.d.ts

@@ -33,7 +33,7 @@ export declare class TeamOrchestrator {
         clearSession?: boolean;
         clearHistory?: boolean;
     }): Promise<void>;
-    dispatchEngineer(input: DispatchEngineerInput): Promise<EngineerTaskResult>;
+    dispatchEngineer(input: DispatchEngineerInput, retryCount?: number): Promise<EngineerTaskResult>;
     static classifyError(error: unknown): EngineerFailureResult & {
         cause: unknown;
     };
@@ -41,8 +41,8 @@ export declare class TeamOrchestrator {
         teamId: string;
         cwd: string;
         request: string;
-        leadEngineer: EngineerName;
-        challengerEngineer: EngineerName;
+        leadEngineer?: EngineerName;
+        challengerEngineer?: EngineerName;
         model?: string;
         abortSignal?: AbortSignal;
         onLeadEvent?: ClaudeSessionEventHandler;
@@ -53,7 +53,14 @@ export declare class TeamOrchestrator {
     private reserveEngineer;
     private getEngineerState;
     private normalizeTeamRecord;
+    getAvailableEngineers(team: TeamRecord): EngineerName[];
+    selectPlanEngineers(cwd: string, teamId: string, preferredLead?: EngineerName, preferredChallenger?: EngineerName): Promise<{
+        lead: EngineerName;
+        challenger: EngineerName;
+    }>;
     private buildSessionSystemPrompt;
     private buildEngineerPrompt;
 }
+export declare function getFailureGuidanceText(failureKind: string): string;
+export declare function createActionableError(failure: EngineerFailureResult, originalError: unknown): Error;
 export {};

package/dist/manager/team-orchestrator.js

@@ -88,7 +88,7 @@ export class TeamOrchestrator {
             context: options?.clearSession ? createEmptyEngineerRecord(engineer).context : entry.context,
         }));
     }
-    async dispatchEngineer(input) {
+    async dispatchEngineer(input, retryCount = 0) {
         const team = await this.getOrCreateTeam(input.cwd, input.teamId);
         const engineerState = this.getEngineerState(team, input.engineer);
         await this.reserveEngineer(input.cwd, input.teamId, input.engineer);
@@ -161,6 +161,39 @@ export class TeamOrchestrator {
                 busy: false,
                 busySince: null,
             }));
+            // Handle context exhaustion with automatic retry (max 1 retry)
+            const classified = TeamOrchestrator.classifyError(error);
+            if (classified.failureKind === 'contextExhausted' && retryCount === 0) {
+                // Reset the engineer's session and retry once with fresh session
+                await this.resetEngineer(input.cwd, input.teamId, input.engineer, {
+                    clearSession: true,
+                    clearHistory: false,
+                });
+                // Emit status event before retry
+                await input.onEvent?.({
+                    type: 'status',
+                    text: 'Context exhausted; resetting session and retrying once with a fresh session.',
+                });
+                try {
+                    // Retry dispatch with fresh session (retryCount=1 prevents infinite loop)
+                    // Use the exact same assignment message without modification
+                    return await this.dispatchEngineer(input, 1);
+                }
+                catch (retryError) {
+                    // If retry also fails with a different error, preserve retry failure info
+                    const retryClassified = TeamOrchestrator.classifyError(retryError);
+                    if (retryClassified.failureKind !== classified.failureKind) {
+                        // Create an error that shows both failures
+                        const combinedMessage = `Initial: ${classified.failureKind} (${classified.message})\n` +
+                            `After retry: ${retryClassified.failureKind} (${retryClassified.message})`;
+                        const combinedError = new Error(combinedMessage);
+                        Object.assign(combinedError, { cause: retryError });
+                        throw combinedError;
+                    }
+                    // Same error type on retry, throw the retry error (more recent state)
+                    throw retryError;
+                }
+            }
             throw error;
         }
     }
@@ -192,14 +225,13 @@ export class TeamOrchestrator {
         };
     }
     async planWithTeam(input) {
-        if (input.leadEngineer === input.challengerEngineer) {
-            throw new Error('Choose two different engineers for plan synthesis.');
-        }
+        // Auto-select engineers if not provided
+        const { lead: leadEngineer, challenger: challengerEngineer } = await this.selectPlanEngineers(input.cwd, input.teamId, input.leadEngineer, input.challengerEngineer);
         const [leadDraft, challengerDraft] = await Promise.all([
             this.dispatchEngineer({
                 teamId: input.teamId,
                 cwd: input.cwd,
-                engineer: input.leadEngineer,
+                engineer: leadEngineer,
                 mode: 'explore',
                 message: buildPlanDraftRequest('lead', input.request),
                 model: input.model,
@@ -209,7 +241,7 @@ export class TeamOrchestrator {
             this.dispatchEngineer({
                 teamId: input.teamId,
                 cwd: input.cwd,
-                engineer: input.challengerEngineer,
+                engineer: challengerEngineer,
                 mode: 'explore',
                 message: buildPlanDraftRequest('challenger', input.request),
                 model: input.model,
@@ -237,8 +269,8 @@ export class TeamOrchestrator {
         return {
             teamId: input.teamId,
             request: input.request,
-            leadEngineer: input.leadEngineer,
-            challengerEngineer: input.challengerEngineer,
+            leadEngineer,
+            challengerEngineer,
             drafts,
             synthesis: parsedSynthesis.synthesis,
             recommendedQuestion: parsedSynthesis.recommendedQuestion,
@@ -294,6 +326,47 @@ export class TeamOrchestrator {
             engineers: createEmptyTeamRecord(team.id, team.cwd).engineers.map((engineer) => engineerMap.get(engineer.name) ?? engineer),
         };
     }
+    getAvailableEngineers(team) {
+        const now = Date.now();
+        return team.engineers
+            .filter((engineer) => {
+            if (!engineer.busy)
+                return true;
+            // If an engineer has been marked busy but the lease expired, they're available
+            if (engineer.busySince) {
+                const leaseExpired = now - new Date(engineer.busySince).getTime() > BUSY_LEASE_MS;
+                return leaseExpired;
+            }
+            return false;
+        })
+            .sort((a, b) => {
+            // Prefer engineers with lower context pressure and less-recently-used
+            const aContext = a.context.estimatedContextPercent ?? 0;
+            const bContext = b.context.estimatedContextPercent ?? 0;
+            if (aContext !== bContext) {
+                return aContext - bContext; // Lower context first
+            }
+            // If context is equal, prefer less-recently-used
+            const aTime = a.lastUsedAt ? new Date(a.lastUsedAt).getTime() : 0;
+            const bTime = b.lastUsedAt ? new Date(b.lastUsedAt).getTime() : 0;
+            return aTime - bTime; // Earlier usage time first
+        })
+            .map((engineer) => engineer.name);
+    }
+    async selectPlanEngineers(cwd, teamId, preferredLead, preferredChallenger) {
+        const team = await this.getOrCreateTeam(cwd, teamId);
+        const available = this.getAvailableEngineers(team);
+        if (available.length < 2) {
+            throw new Error(`Not enough available engineers for dual planning. Need 2, found ${available.length}.`);
+        }
+        const lead = preferredLead ?? available[0];
+        const foundChallenger = preferredChallenger ?? available.find((e) => e !== lead);
+        const challenger = foundChallenger ?? available[1];
+        if (lead === challenger) {
+            throw new Error('Cannot use the same engineer for both lead and challenger.');
+        }
+        return { lead, challenger };
+    }
     buildSessionSystemPrompt(engineer, mode) {
         return [
             this.engineerSessionPrompt,
@@ -398,3 +471,26 @@ function normalizeOptionalSection(value) {
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+export function getFailureGuidanceText(failureKind) {
+    switch (failureKind) {
+        case 'contextExhausted':
+            return 'Context exhausted after using all available tokens. The engineer was reset and the assignment retried once. If it still fails, the task may be too large; consider breaking it into smaller steps.';
+        case 'engineerBusy':
+            return 'This engineer is currently working on another assignment. Wait for them to finish, choose a different engineer, or try again shortly.';
+        case 'toolDenied':
+            return 'A tool permission was denied during the assignment. Check the approval policy and tool permissions, then retry.';
+        case 'aborted':
+            return 'The assignment was cancelled by the user or an abort signal was triggered. Review the request and try again.';
+        case 'sdkError':
+            return 'An SDK error occurred during the assignment. Check logs for details, ensure the Claude session is healthy, and retry.';
+        default:
+            return 'An unknown error occurred during the assignment. Check logs and retry.';
+    }
+}
+export function createActionableError(failure, originalError) {
+    const guidance = getFailureGuidanceText(failure.failureKind);
+    const errorMessage = `[${failure.failureKind}] ${failure.message}\n\n` + `Next steps: ${guidance}`;
+    const error = new Error(errorMessage);
+    Object.assign(error, { cause: originalError });
+    return error;
+}

package/dist/plugin/agent-hierarchy.js

@@ -98,7 +98,7 @@ export function buildCtoAgentConfig(prompts) {
 }
 export function buildEngineerAgentConfig(prompts, engineer) {
     return {
-        description: `${engineer} is a persistent engineer who works through one Claude Code session and remembers prior turns.`,
+        description: `${engineer} is a persistent engineer who works through one Claude Code session and remembers prior turns. Receives structured assignments (goal, mode, context, acceptance criteria, relevant paths, constraints, verification).`,
         mode: 'subagent',
         hidden: false,
         color: '#D97757',
@@ -108,7 +108,7 @@ export function buildEngineerAgentConfig(prompts, engineer) {
 }
 export function buildTeamPlannerAgentConfig(prompts) {
     return {
-        description: 'Runs dual-engineer planning by calling plan_with_team. Asks for engineer names if not provided.',
+        description: 'Runs dual-engineer planning by calling plan_with_team. Automatically selects two non-overlapping available engineers if engineer names are not provided.',
         mode: 'subagent',
         hidden: false,
         color: '#D97757',

package/dist/plugin/claude-manager.plugin.js

@@ -1,7 +1,7 @@
 import { tool } from '@opencode-ai/plugin';
 import { managerPromptRegistry } from '../prompts/registry.js';
 import { isEngineerName } from '../team/roster.js';
-import { TeamOrchestrator } from '../manager/team-orchestrator.js';
+import { TeamOrchestrator, createActionableError, getFailureGuidanceText, } from '../manager/team-orchestrator.js';
 import { AGENT_CTO, AGENT_TEAM_PLANNER, ENGINEER_AGENT_IDS, ENGINEER_AGENT_NAMES, buildCtoAgentConfig, buildEngineerAgentConfig, buildTeamPlannerAgentConfig, denyRestrictedToolsGlobally, } from './agent-hierarchy.js';
 import { getActiveTeamSession, getOrCreatePluginServices, getPersistedActiveTeam, getWrapperSessionMapping, setActiveTeamSession, setPersistedActiveTeam, setWrapperSessionMapping, } from './service-factory.js';
 const MODEL_ENUM = ['claude-opus-4-6', 'claude-sonnet-4-6'];
@@ -105,30 +105,32 @@ export const ClaudeManagerPlugin = async ({ worktree }) => {
                 },
             }),
             plan_with_team: tool({
-                description: 'Run dual-engineer plan synthesis. Two engineers explore in parallel (lead + challenger), then their plans are synthesized into one stronger plan.',
+                description: 'Run dual-engineer plan synthesis. Two engineers explore in parallel (lead + challenger), then their plans are synthesized into one stronger plan. Automatically selects distinct available engineers if names are not provided.',
                 args: {
                     request: tool.schema.string().min(1),
-                    leadEngineer: tool.schema.enum(['Tom', 'John', 'Maya', 'Sara', 'Alex']),
-                    challengerEngineer: tool.schema.enum(['Tom', 'John', 'Maya', 'Sara', 'Alex']),
+                    leadEngineer: tool.schema.enum(['Tom', 'John', 'Maya', 'Sara', 'Alex']).optional(),
+                    challengerEngineer: tool.schema.enum(['Tom', 'John', 'Maya', 'Sara', 'Alex']).optional(),
                     model: tool.schema.enum(MODEL_ENUM).optional(),
                 },
                 async execute(args, context) {
                     const teamId = getActiveTeamSession(context.worktree) ?? context.sessionID;
+                    // Pre-determine engineers for event labeling (using orchestrator selection logic)
+                    const { lead, challenger } = await services.orchestrator.selectPlanEngineers(context.worktree, teamId, args.leadEngineer, args.challengerEngineer);
                     annotateToolRun(context, 'Running dual-engineer plan synthesis', {
                         teamId,
-                        lead: args.leadEngineer,
-                        challenger: args.challengerEngineer,
+                        lead,
+                        challenger,
                     });
                     const result = await services.orchestrator.planWithTeam({
                         teamId,
                         cwd: context.worktree,
                         request: args.request,
-                        leadEngineer: args.leadEngineer,
-                        challengerEngineer: args.challengerEngineer,
+                        leadEngineer: lead,
+                        challengerEngineer: challenger,
                         model: args.model,
                         abortSignal: context.abort,
-                        onLeadEvent: (event) => reportClaudeEvent(context, args.leadEngineer, event),
-                        onChallengerEvent: (event) => reportClaudeEvent(context, args.challengerEngineer, event),
+                        onLeadEvent: (event) => reportClaudeEvent(context, lead, event),
+                        onChallengerEvent: (event) => reportClaudeEvent(context, challenger, event),
                         onSynthesisEvent: (event) => reportPlanSynthesisEvent(context, event),
                     });
                     context.metadata({
@@ -386,6 +388,7 @@ async function runEngineerAssignment(input, context) {
         failure.teamId = input.teamId;
         failure.engineer = input.engineer;
         failure.mode = input.mode;
+        const guidance = getFailureGuidanceText(failure.failureKind);
         context.metadata({
             title: `❌ ${input.engineer} failed (${failure.failureKind})`,
             metadata: {
@@ -393,9 +396,10 @@ async function runEngineerAssignment(input, context) {
                 engineer: failure.engineer,
                 failureKind: failure.failureKind,
                 message: failure.message.slice(0, 200),
+                guidance,
             },
         });
-        throw error;
+        throw createActionableError(failure, error);
     }
     await services.orchestrator.recordWrapperExchange(context.worktree, input.teamId, input.engineer, context.sessionID, input.mode, input.message, result.finalText);
     context.metadata({
@@ -505,6 +509,16 @@ function reportClaudeEvent(context, engineer, event) {
         });
         return;
     }
+    if (event.type === 'status') {
+        context.metadata({
+            title: `ℹ️ ${engineer}: ${event.text}`,
+            metadata: {
+                engineer,
+                status: event.text,
+            },
+        });
+        return;
+    }
     if (event.type === 'init') {
         context.metadata({
             title: `⚡ ${engineer} session ready`,

package/dist/prompts/registry.js

@@ -1,68 +1,93 @@
 export const managerPromptRegistry = {
     ctoSystemPrompt: [
         'You are a principal engineer orchestrating a team of AI-powered engineers.',
-        'You multiply your output by delegating precisely and reviewing critically.',
-        'Every prompt you send to an engineer costs time and tokens. Make each one count.',
-        '',
-        'Understand first:',
-        '- Before asking the user anything, extract what you can from the user message, codebase (read/grep/glob/codesearch), prior engineer results, and `websearch`/`webfetch` when relevant.',
-        '- Ask the user only when the answer would materially change scope, architecture, risk, or how you verify the outcome—and you cannot resolve it from those sources.',
-        '- Do not ask for facts you can discover yourself: file paths, current behavior, architecture, or framework conventions.',
-        '- Before using `question`, silently check: is it in the user message? answerable from code or transcripts? from web? If still blocked, is this a real decision or only uncertainty tolerance?',
-        '- Identify what already exists in the codebase before creating anything new.',
-        '- Think about what could go wrong and address it upfront.',
-        '- When a bug is reported, always explore the root cause before implementing a fix. No fix without investigation. If three fix attempts fail, question the architecture, not the hypothesis.',
-        '',
-        'Questions (high bar):',
-        '- Good questions resolve irreversible choices, product tradeoffs, or ambiguous success criteria that the codebase cannot answer.',
-        '- Bad questions ask for information already in context, or vague prompts like "what exactly do you want?" when you can give a concrete recommendation and what would change your mind.',
-        '- Each `question` should name the blocked decision, offer 2–3 concrete options, state your recommendation, and what breaks if the user picks differently.',
-        '- Use the `question` tool only when you cannot proceed safely from available evidence. One high-leverage question at a time, with a sensible fallback if the user defers.',
-        '',
-        'Challenge the framing:',
-        '- Not a mandatory opener: if the request is concrete, derive context first; reframe only when it would change what you build.',
-        '- Before planning, ask what the user is actually trying to achieve, not just what they asked for.',
-        '- If the request sounds like a feature ("add photo upload"), ask what job-to-be-done it serves. The real feature might be larger or different.',
-        '- One good reframe question saves more time than ten implementation questions.',
-        '',
-        'Plan and decompose:',
-        '- Break work into independent pieces that can run in parallel. Two engineers exploring in parallel then synthesizing beats one engineer doing everything sequentially.',
-        "- For medium or large tasks, delegate dual-engineer exploration and synthesis to the `team-planner` subagent: use `task(subagent_type: 'team-planner', ...)`. When tasking engineer subagents directly, use lowercase subagent IDs: tom, john, maya, sara, alex.",
-        '- Define clear success criteria before delegating. A good assignment includes: what to do, why, which files/areas are relevant, and how to verify it worked.',
-        '',
-        'Delegate through the Task tool:',
-        '- Tom, John, Maya, Sara, and Alex are persistent engineers. Each keeps a Claude Code session that remembers prior turns.',
-        '- Reuse the same engineer when follow-up work belongs to their prior context.',
-        '- Only one implementing engineer should modify the worktree at a time. Parallelize exploration freely.',
-        '- Do not delegate without telling the engineer what done looks like.',
-        '',
-        'Review and iterate:',
-        '- Review diffs with `git_diff`, inspect changed files with `git_status`, and use `git_log` for recent context.',
-        '- Give specific, actionable feedback. Not "this could be better" but "this is wrong because X, fix it by doing Y."',
-        '- Trust engineer findings but verify critical claims. Do not re-examine every file they already reviewed.',
-        '- If something fails, figure out what you missed in the assignment, not just what the engineer got wrong.',
-        '- After an engineer reports implementation done, review the diff looking for issues that pass tests but break in production: race conditions, N+1 queries, missing error handling, trust boundary violations, stale reads, forgotten enum cases.',
-        '- Auto-fix mechanical issues by sending a follow-up to the same engineer. Surface genuinely ambiguous issues to the user.',
-        '- Check scope: did the engineer build what was asked — nothing more, nothing less?',
-        '',
-        'Verify before declaring done:',
+        'Your role is to decompose work, delegate precisely, review diffs for production risks, and verify outcomes.',
+        'You do not write code. All edits go through engineers. You multiply output by coordinating parallel work and catching issues others miss.',
+        '',
+        '# Operating Loop: Orient → Classify → Plan → Delegate → Review → Verify → Close',
+        '',
+        '## Orient: Understand the request',
+        '- Extract what you can from the user message, codebase (read/grep/glob/codesearch), prior engineer results, and `websearch`/`webfetch` when relevant.',
+        '- Light investigation is fine: read files briefly to understand scope, check what already exists, avoid re-inventing.',
+        '- When a bug is reported, ask: what is the root cause? Do not assume. Delegate root-cause exploration if the answer is in code the user should review first.',
+        '- If requirements are vague or architecture is unclear, use `question` tool with 2–3 concrete options, your recommendation, and what breaks if user picks differently.',
+        '- Only ask when the decision will materially change scope, architecture, risk, or how you verify—and you cannot resolve it from context.',
+        '',
+        '## Classify: Frame the work',
+        '- Is this a bug fix, feature, refactor, or something else?',
+        '- What could go wrong? Is it reversible or irreversible? Can it fail in prod?',
+        '- Does it require careful rollout, data migration, observability, or backwards compatibility handling?',
+        '- Are there decisions the user has not explicitly made (architecture, scope, deployment strategy)?',
+        '',
+        '## Plan: Decompose into engineer work',
+        '- For small, focused tasks: delegate to a named engineer with structured context (goal, acceptance criteria, relevant files, constraints, verification).',
+        "- For medium or large tasks: use `task(subagent_type: 'team-planner', ...)` for dual-engineer exploration and plan synthesis.",
+        '  - Team-planner automatically selects two non-overlapping engineers by availability and context; you may optionally specify lead and challenger.',
+        '  - Challenger engineer identifies missing decisions, risks, and scope gaps before implementation.',
+        '- Break work into independent pieces that can run in parallel. Two engineers exploring then synthesizing beats one engineer doing everything sequentially.',
+        '- Before delegating, state your success criteria, not just the task. What done looks like. How you will verify it.',
+        '',
+        '## Delegate: Send precise assignments',
+        "- For single-engineer work: use `task(subagent_type: 'tom'|'john'|'maya'|'sara'|'alex', ...)` and structure the prompt with goal, acceptance criteria, relevant files, constraints, and verification.",
+        "- For dual-engineer planning: use `task(subagent_type: 'team-planner', ...)` which will lead + challenger synthesis.",
+        '- Each assignment includes: goal, acceptance criteria, relevant files/areas, constraints, and verification method.',
+        '- Reuse the same engineer when follow-up work builds on their prior context.',
+        '- Only one implementing engineer modifies the worktree at a time. Parallelize exploration and research freely.',
+        '',
+        '## Review: Inspect diffs for production safety',
+        '- After an engineer reports implementation done, review the diff with `git_diff` before declaring it complete.',
+        '- Use `git_log` and `git_status` for recent context.',
+        '- Check for these production-risk patterns (issues tests may not catch):',
+        '  - Race conditions: concurrent access to shared state, missing locks or atomic operations.',
+        '  - N+1 queries: loops that fetch data repeatedly instead of batch-loading.',
+        '  - Missing error handling: uncaught exceptions, unhandled promise rejections, missing null checks.',
+        '  - Trust boundary violations: user input used without validation, permissions not checked.',
+        '  - Stale reads: reading state without synchronization or caching without invalidation logic.',
+        '  - Forgotten enum cases: switches without default, missing case handlers.',
+        '  - Backwards compatibility: breaking API changes, schema migrations without rollback plan.',
+        '  - Observability gaps: no logging, metrics, or tracing for critical paths.',
+        '  - Rollout risk: changes that must be coordinated across services or require staged rollout.',
+        '- Give specific, actionable feedback. Not "this could be better" but "line 42 has a race condition because X; fix it by doing Y."',
+        '- Trust engineer findings but verify critical claims.',
+        '- Check scope: did the engineer build what was asked—nothing more, nothing less?',
+        '',
+        '## Verify: Run checks before shipping',
         '- After review passes, dispatch an engineer in verify mode to run the most relevant checks (tests, lint, typecheck, build) for what changed.',
         '- Do not declare a task complete until verification passes. If it fails, fix and re-verify.',
         '',
-        'Constraints:',
+        '## Close: Report outcome to user',
+        '- If everything verifies and passes review, tell the user the work is done and what changed.',
+        '- If a recommended question from planning was not yet surfaced to the user, surface it now with `question` tool before closing.',
+        '- If the work discovered unexpected scope or product decisions, ask the user before proceeding further.',
+        '',
+        '# Decision-Making Rules',
+        '',
+        '- Questions: Use the `question` tool when a decision will materially affect scope, architecture, or how you verify the outcome. Name the decision, offer 2–3 concrete options, state your recommendation, and say what breaks if the user picks differently. One high-leverage question at a time.',
+        '- Reframing: Before planning, ask what the user is actually trying to achieve, not just what they asked for. If the request sounds like a feature, ask what job-to-be-done it serves.',
+        '- Engineer selection: When assigning to a single engineer, prefer lower context pressure and less-recently-used engineers. Reuse if follow-up work builds on prior context.',
+        '- Failure handling:',
+        "  - contextExhausted: The engineer's session ran out of tokens. The system automatically resets and retries once with the same task on a fresh session.",
+        '  - sdkError or toolDenied: The underlying SDK failed or a tool call was denied. Investigate the error, adjust constraints, and retry.',
+        '  - engineerBusy: Wait, or choose a different engineer.',
+        '  - aborted: The user cancelled the work. Stop and report the cancellation.',
+        '',
+        '# Constraints',
+        '',
         '- Do not edit files or run bash directly. Engineers do the hands-on work.',
-        '- Do not read files or grep when an engineer can answer the question faster.',
+        '- Light investigation is fine for orientation (read, grep, glob). Delegate deeper exploration if it saves the engineer context.',
         '- Communicate proactively. If the plan changes or you discover something unexpected, tell the user.',
-        '- Ask follow-up questions when exploration, engineer results, or diffs expose a product or architecture tradeoff you could not have known at the start. Prefer that timing over opening with speculative clarifiers.',
+        '- Do not proceed with implementation if you cannot state success criteria.',
     ].join('\n'),
     engineerAgentPrompt: [
         "You are a named engineer on the CTO's team.",
-        'Your job is to run assignments through the `claude` tool, which connects to a persistent Claude Code session that remembers your prior turns.',
+        'The CTO sends assignments through a structured prompt containing: goal, mode (explore/implement/verify), context, acceptance criteria, relevant paths, constraints, and verification method.',
+        'Your job is to parse the assignment and run it through the `claude` tool, which connects to a persistent Claude Code session that remembers your prior turns.',
         '',
-        'Frame each assignment well:',
-        '- Include relevant context, file paths, and constraints the CTO provided.',
+        'How to handle assignments:',
+        '- Extract goal, mode, acceptance criteria, relevant files, and verification from the prompt.',
+        '- If any critical field is missing (e.g., no verification method), ask the CTO for clarification before proceeding.',
+        '- Frame the assignment for Claude Code using the provided structure.',
         '- Specify the work mode: explore (investigate, no edits), implement (make changes and verify), or verify (run checks and report).',
-        "- If the CTO's assignment is unclear, ask for clarification before sending it to Claude Code.",
         '',
         'Your wrapper context from prior turns is reloaded automatically. Use it to avoid repeating work or re-explaining context that Claude Code already knows.',
         "Return the tool result directly. Add your own commentary only when something was unexpected or needs the CTO's attention.",
@@ -71,8 +96,27 @@ export const managerPromptRegistry = {
         'You are an expert software engineer working inside Claude Code.',
         'Start with the smallest investigation that resolves the key uncertainty, then act.',
         'Follow repository conventions, AGENTS.md, and any project-level instructions.',
-        'Verify your own work before reporting done. Run the most relevant check (test, lint, typecheck, build) for what you changed.',
-        'Review your own diff before reporting done. Look for issues tests would not catch: race conditions, missing error handling, hardcoded values, incomplete enum handling.',
+        '',
+        'When investigating bugs:',
+        '- Always explore the root cause before implementing a fix. Do not assume; verify.',
+        '- If three fix attempts fail, question the architecture, not the hypothesis.',
+        '',
+        'When writing code:',
+        '- Consider rollout/migration/observability implications: Will this require staged rollout, data migration, new metrics, or log/trace points?',
+        '- Check for backwards compatibility: Will this change break existing APIs, integrations, or data formats?',
+        '- Think about failure modes: What happens if this code fails? Is it recoverable? Is there an audit trail?',
+        '',
+        'Verify your work before reporting done:',
+        '- Run the most relevant check (test, lint, typecheck, build) for what you changed.',
+        '- Review your own diff. Look for these issues tests may not catch:',
+        '  - Race conditions (concurrent access, missing locks).',
+        '  - N+1 queries or similar performance patterns.',
+        '  - Missing error handling or unhandled edge cases.',
+        '  - Hardcoded values that should be configurable.',
+        '  - Incomplete enum handling (missing cases).',
+        '  - Trust boundary violations (user input not validated).',
+        '  - Stale reads or cache invalidation bugs.',
+        '',
         'Report blockers immediately with exact error output. Do not retry silently more than once.',
         'Do not run git commit, git push, git reset, git checkout, or git stash.',
     ].join('\n'),
@@ -80,7 +124,12 @@ export const managerPromptRegistry = {
         'You are synthesizing two independent engineering plans into one stronger, unified plan.',
         'Compare the lead and challenger plans on clarity, feasibility, risk, and fit to the user request.',
         'Prefer the simplest path that fully addresses the goal. Surface tradeoffs honestly.',
-        'If the plans disagree on something only the user can decide, surface exactly one recommended question and one recommended answer.',
+        '',
+        'Identify the single most important decision the user must make to execute this plan safely and correctly.',
+        '- Look for disagreements between plans, scope boundaries, deployment/rollout strategy, backwards compatibility, or architectural tradeoffs.',
+        '- The user may have stated preferences in their request; check if anything is still unsolved.',
+        'Write it as Recommended Question and Recommended Answer. Only write NONE if no external decision is genuinely required.',
+        '',
         'Do not editorialize or over-explain. Be direct and concise.',
         '',
         'Use this output format exactly:',
@@ -95,8 +144,9 @@ export const managerPromptRegistry = {
         'You are the team planner. Your only job is to invoke `plan_with_team`.',
         '`plan_with_team` dispatches two engineers in parallel (lead + challenger) then synthesizes their plans.',
         '',
-        'If the task includes a lead engineer and a challenger engineer, call `plan_with_team` immediately.',
-        'If either engineer name is missing, use `question` to ask: which engineers should lead and challenge (Tom, John, Maya, Sara, or Alex)?',
+        'Call `plan_with_team` immediately with the task and any engineer names provided.',
+        '- If lead and challenger engineer names are both specified, use them.',
+        '- If either name is missing, `plan_with_team` will auto-select two non-overlapping engineers based on availability and context.',
         'Do not attempt any planning or analysis yourself. Delegate entirely to `plan_with_team`.',
     ].join('\n'),
     contextWarnings: {

package/dist/src/manager/team-orchestrator.d.ts

@@ -33,7 +33,7 @@ export declare class TeamOrchestrator {
         clearSession?: boolean;
         clearHistory?: boolean;
     }): Promise<void>;
-    dispatchEngineer(input: DispatchEngineerInput): Promise<EngineerTaskResult>;
+    dispatchEngineer(input: DispatchEngineerInput, retryCount?: number): Promise<EngineerTaskResult>;
     static classifyError(error: unknown): EngineerFailureResult & {
         cause: unknown;
     };
@@ -41,8 +41,8 @@ export declare class TeamOrchestrator {
         teamId: string;
         cwd: string;
         request: string;
-        leadEngineer: EngineerName;
-        challengerEngineer: EngineerName;
+        leadEngineer?: EngineerName;
+        challengerEngineer?: EngineerName;
         model?: string;
         abortSignal?: AbortSignal;
         onLeadEvent?: ClaudeSessionEventHandler;
@@ -53,7 +53,14 @@ export declare class TeamOrchestrator {
     private reserveEngineer;
     private getEngineerState;
     private normalizeTeamRecord;
+    getAvailableEngineers(team: TeamRecord): EngineerName[];
+    selectPlanEngineers(cwd: string, teamId: string, preferredLead?: EngineerName, preferredChallenger?: EngineerName): Promise<{
+        lead: EngineerName;
+        challenger: EngineerName;
+    }>;
     private buildSessionSystemPrompt;
     private buildEngineerPrompt;
 }
+export declare function getFailureGuidanceText(failureKind: string): string;
+export declare function createActionableError(failure: EngineerFailureResult, originalError: unknown): Error;
 export {};