overseer.update_phases
Modify phase definitions in project workflows by renaming, updating descriptions, or adjusting steps, deliverables, and completion criteria.
Instructions
Updates existing phase definitions (rename, modify description, add/remove steps, deliverables, done criteria).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| repo_root | Yes | Root path of the repository | |
| modifications | Yes | List of modifications to apply |
Implementation Reference
- src/tools/update-phases.ts:61-253 (handler)The main handler function that executes the tool logic: reads existing phases from PHASES.md, applies modifications (add, update, remove), and writes updated phases back to the file.
export async function handleUpdatePhases( args: { repo_root: string; modifications: Array<{ operation: 'add' | 'update' | 'remove'; phase_id?: string; phase?: { id: string; name: string; description: string; deliverables?: string[]; done_criteria?: string[]; }; }>; }, phaseManager: PhaseManager ): Promise<{ success: boolean; message: string; changes_applied: { added: string[]; updated: string[]; removed: string[]; }; files_written: string[]; errors: string[]; }> { const errors: string[] = []; const added: string[] = []; const updated: string[] = []; const removed: string[] = []; const filesWritten: string[] = []; try { // Resolve repo path let repoPath = args.repo_root; if (!repoPath.startsWith('/')) { repoPath = join(homedir(), 'dev', repoPath); } repoPath = FSUtils.expandPath(repoPath); // Extract repo name from path const repoName = repoPath.split('/').pop() || 'unknown'; // Read existing phases // We need to create a RepoHandler that can read from the absolute path // For now, let's read directly and parse const phasesPath = join(repoPath, 'PHASES.md'); if (!FSUtils.fileExists(phasesPath)) { return { success: false, message: 'Project not found. Run plan_project first.', changes_applied: { added: [], updated: [], removed: [] }, files_written: [], errors: ['PHASES.md not found'], }; } // Use RepoHandler with absolute path (handles paths with spaces) const repoHandler = new RepoHandler(); let projectPhases = repoHandler.readPhasesIndexFromPath(repoPath); if (!projectPhases) { return { success: false, message: 'Project not found. Run plan_project first.', changes_applied: { added: [], updated: [], removed: [] }, files_written: [], errors: ['PHASES.md not found'], }; } // Apply modifications for (const mod of args.modifications) { try { if (mod.operation === 'add') { if (!mod.phase) { errors.push('Phase data required for add operation'); continue; } // Validate required fields if (!mod.phase.id || !mod.phase.name || !mod.phase.description) { errors.push('Phase must have id, name, and description'); continue; } // Check if phase ID already exists if (projectPhases.phases.some(p => p.id === mod.phase!.id)) { errors.push(`Phase ID ${mod.phase.id} already exists`); continue; } // Add phase const newPhase: PhaseInfo = { id: mod.phase.id, name: mod.phase.name, status: 'pending', description: mod.phase.description, deliverables: mod.phase.deliverables, done_criteria: mod.phase.done_criteria, }; projectPhases.phases.push(newPhase); added.push(mod.phase.id); } else if (mod.operation === 'update') { if (!mod.phase_id) { errors.push('phase_id required for update operation'); continue; } const phaseIndex = projectPhases.phases.findIndex(p => p.id === mod.phase_id); if (phaseIndex === -1) { errors.push(`Phase ID ${mod.phase_id} not found`); continue; } if (!mod.phase) { errors.push('Phase data required for update operation'); continue; } // Update phase const existingPhase = projectPhases.phases[phaseIndex]; projectPhases.phases[phaseIndex] = { ...existingPhase, name: mod.phase.name || existingPhase.name, description: mod.phase.description || existingPhase.description, deliverables: mod.phase.deliverables !== undefined ? mod.phase.deliverables : existingPhase.deliverables, done_criteria: mod.phase.done_criteria !== undefined ? mod.phase.done_criteria : existingPhase.done_criteria, }; updated.push(mod.phase_id); } else if (mod.operation === 'remove') { if (!mod.phase_id) { errors.push('phase_id required for remove operation'); continue; } const phaseIndex = projectPhases.phases.findIndex(p => p.id === mod.phase_id); if (phaseIndex === -1) { errors.push(`Phase ID ${mod.phase_id} not found`); continue; } projectPhases.phases.splice(phaseIndex, 1); removed.push(mod.phase_id); } } catch (error) { const errorMsg = error instanceof Error ? error.message : String(error); errors.push(`Failed to apply modification: ${errorMsg}`); } } // Write updated PHASES.md if (added.length > 0 || updated.length > 0 || removed.length > 0) { try { repoHandler.writePhasesIndexToPath(repoPath, projectPhases); filesWritten.push(join(repoPath, 'PHASES.md')); } catch (error) { errors.push(`Failed to write PHASES.md: ${error}`); } } const success = errors.length === 0; const message = success ? `Applied ${added.length} additions, ${updated.length} updates, ${removed.length} removals` : `Partially applied changes with ${errors.length} error(s)`; return { success, message, changes_applied: { added, updated, removed, }, files_written: filesWritten, errors, }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return { success: false, message: `Failed to update phases: ${errorMessage}`, changes_applied: { added: [], updated: [], removed: [] }, files_written: [], errors: [errorMessage], }; } } - src/tools/update-phases.ts:8-59 (schema)Defines the tool schema including name, description, and detailed inputSchema for modifications.
export function createUpdatePhasesTool(phaseManager: PhaseManager): Tool { return { name: 'overseer.update_phases', description: 'Updates existing phase definitions (rename, modify description, add/remove steps, deliverables, done criteria).', inputSchema: { type: 'object', required: ['repo_root', 'modifications'], properties: { repo_root: { type: 'string', description: 'Root path of the repository', }, modifications: { type: 'array', items: { type: 'object', properties: { operation: { type: 'string', enum: ['add', 'update', 'remove'], description: 'Operation to perform', }, phase_id: { type: 'string', description: 'Phase ID to update or remove (required for update/remove)', }, phase: { type: 'object', description: 'Phase data (required for add/update)', properties: { id: { type: 'string' }, name: { type: 'string' }, description: { type: 'string' }, deliverables: { type: 'array', items: { type: 'string' }, }, done_criteria: { type: 'array', items: { type: 'string' }, }, }, }, }, required: ['operation'], }, description: 'List of modifications to apply', }, }, }, }; } - src/tools/index.ts:54-55 (registration)Tool handler registration in the central switch dispatcher in handleToolCall.
case 'overseer.update_phases': return await handleUpdatePhases(args, context.phaseManager); - src/tools/index.ts:27-27 (registration)Tool creation and registration in the createTools array.
createUpdatePhasesTool(context.phaseManager), - src/tools/index.ts:9-9 (registration)Import of the tool creator and handler from update-phases.ts.
import { createUpdatePhasesTool, handleUpdatePhases } from './update-phases.js';