@phi-code-admin/phi-code 0.56.3

package/extensions/phi/orchestrator.ts

@@ -0,0 +1,411 @@
+/**
+ * Orchestrator Extension - High-level project planning and task orchestration
+ *
+ * Provides tools to break down high-level project descriptions into structured 
+ * specifications and actionable task lists. Helps manage complex projects by
+ * creating organized plans and tracking progress.
+ *
+ * Features:
+ * - /plan command for interactive planning
+ * - orchestrate tool callable by LLM
+ * - Automatic directory structure creation
+ * - Timestamped spec and todo files
+ * - Task status tracking (pending/done)
+ *
+ * Usage:
+ * 1. Copy to packages/coding-agent/extensions/phi/orchestrator.ts
+ * 2. Use /plan <description> to create project plans
+ * 3. Plans are stored in .phi/plans/ directory
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "phi-code";
+import { writeFile, mkdir, readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+interface TaskItem {
+	id: number;
+	description: string;
+	status: "pending" | "done";
+	subtasks?: TaskItem[];
+}
+
+interface ProjectPlan {
+	title: string;
+	description: string;
+	timestamp: string;
+	goals: string[];
+	requirements: string[];
+	architecture: string[];
+	tasks: TaskItem[];
+}
+
+export default function orchestratorExtension(pi: ExtensionAPI) {
+	const plansDir = join(process.cwd(), ".phi", "plans");
+
+	/**
+	 * Ensure plans directory exists
+	 */
+	async function ensurePlansDirectory() {
+		try {
+			await mkdir(plansDir, { recursive: true });
+		} catch (error) {
+			console.warn("Failed to create plans directory:", error);
+		}
+	}
+
+	/**
+	 * Generate timestamp for file naming
+	 */
+	function getTimestamp(): string {
+		return new Date().toISOString().replace(/[:.]/g, "-").replace("T", "_").slice(0, 19);
+	}
+
+	/**
+	 * Analyze description and create structured project plan
+	 */
+	function analyzeProject(description: string): ProjectPlan {
+		const timestamp = new Date().toISOString();
+		
+		// Extract title from first sentence or use generic title
+		let title = "Project Plan";
+		const firstSentence = description.split('.')[0].trim();
+		if (firstSentence.length > 10 && firstSentence.length < 100) {
+			title = firstSentence;
+		}
+
+		// Basic analysis to extract goals, requirements, and tasks
+		const lines = description.split('\n').filter(line => line.trim());
+		const goals: string[] = [];
+		const requirements: string[] = [];
+		const architecture: string[] = [];
+		const tasks: TaskItem[] = [];
+
+		// Simple pattern matching for structure
+		let taskId = 1;
+		for (const line of lines) {
+			const trimmed = line.trim();
+			
+			// Look for action words to identify tasks
+			if (trimmed.match(/^(create|build|implement|develop|add|setup|configure|install|write|design|test)/i)) {
+				tasks.push({
+					id: taskId++,
+					description: trimmed,
+					status: "pending"
+				});
+			}
+			// Look for requirements keywords
+			else if (trimmed.match(/(require|need|must|should have|depend)/i)) {
+				requirements.push(trimmed);
+			}
+			// Look for architecture/tech keywords
+			else if (trimmed.match(/(using|with|technology|framework|database|api|service)/i)) {
+				architecture.push(trimmed);
+			}
+			// Everything else could be goals
+			else if (trimmed.length > 10) {
+				goals.push(trimmed);
+			}
+		}
+
+		// If no explicit tasks found, break down description into logical steps
+		if (tasks.length === 0) {
+			const generalTasks = [
+				"Analyze requirements and define scope",
+				"Design system architecture",
+				"Set up development environment",
+				"Implement core functionality",
+				"Add tests and documentation",
+				"Deploy and validate solution"
+			];
+
+			generalTasks.forEach((task, index) => {
+				tasks.push({
+					id: index + 1,
+					description: task,
+					status: "pending"
+				});
+			});
+		}
+
+		return {
+			title,
+			description,
+			timestamp,
+			goals: goals.length > 0 ? goals : [description],
+			requirements,
+			architecture,
+			tasks
+		};
+	}
+
+	/**
+	 * Generate specification markdown content
+	 */
+	function generateSpecContent(plan: ProjectPlan): string {
+		const timestamp = new Date(plan.timestamp).toLocaleString();
+		
+		return `# ${plan.title}
+
+**Created:** ${timestamp}
+
+## Description
+
+${plan.description}
+
+## Goals
+
+${plan.goals.map(goal => `- ${goal}`).join('\n')}
+
+## Requirements
+
+${plan.requirements.length > 0 
+	? plan.requirements.map(req => `- ${req}`).join('\n')
+	: '- To be defined based on project analysis'
+}
+
+## Architecture
+
+${plan.architecture.length > 0
+	? plan.architecture.map(arch => `- ${arch}`).join('\n')
+	: '- To be designed during implementation planning'
+}
+
+## Implementation Notes
+
+- This specification was generated automatically from the project description
+- Review and refine requirements based on detailed analysis
+- Update architecture section with technical decisions
+- Use the corresponding TODO file to track progress
+
+---
+
+*Generated by Phi Code Orchestrator*
+`;
+	}
+
+	/**
+	 * Generate TODO markdown content  
+	 */
+	function generateTodoContent(plan: ProjectPlan): string {
+		const timestamp = new Date(plan.timestamp).toLocaleString();
+		
+		let todoContent = `# TODO: ${plan.title}
+
+**Created:** ${timestamp}
+
+## Tasks
+
+`;
+
+		plan.tasks.forEach(task => {
+			const checkbox = task.status === "done" ? "[x]" : "[ ]";
+			todoContent += `${checkbox} **Task ${task.id}:** ${task.description}\n`;
+			
+			if (task.subtasks) {
+				task.subtasks.forEach(subtask => {
+					const subCheckbox = subtask.status === "done" ? "[x]" : "[ ]";
+					todoContent += `  ${subCheckbox} ${subtask.description}\n`;
+				});
+			}
+			todoContent += '\n';
+		});
+
+		todoContent += `
+## Progress
+
+- Total tasks: ${plan.tasks.length}
+- Completed: ${plan.tasks.filter(t => t.status === "done").length}
+- Remaining: ${plan.tasks.filter(t => t.status === "pending").length}
+
+## Notes
+
+- Update task status by changing [ ] to [x] when completed
+- Add subtasks under main tasks as needed
+- Use this file to track detailed progress
+
+---
+
+*Generated by Phi Code Orchestrator*
+`;
+
+		return todoContent;
+	}
+
+	/**
+	 * Create project plan files
+	 */
+	async function createPlanFiles(description: string): Promise<{ specFile: string; todoFile: string; plan: ProjectPlan }> {
+		await ensurePlansDirectory();
+
+		const plan = analyzeProject(description);
+		const timestamp = getTimestamp();
+		
+		const specFilename = `spec-${timestamp}.md`;
+		const todoFilename = `todo-${timestamp}.md`;
+		
+		const specPath = join(plansDir, specFilename);
+		const todoPath = join(plansDir, todoFilename);
+
+		const specContent = generateSpecContent(plan);
+		const todoContent = generateTodoContent(plan);
+
+		await writeFile(specPath, specContent, 'utf-8');
+		await writeFile(todoPath, todoContent, 'utf-8');
+
+		return {
+			specFile: specFilename,
+			todoFile: todoFilename,
+			plan
+		};
+	}
+
+	/**
+	 * Orchestrate tool - Create project plans programmatically
+	 */
+	pi.registerTool({
+		name: "orchestrate",
+		label: "Project Orchestrator",
+		description: "Break down high-level project descriptions into structured specifications and task lists",
+		parameters: Type.Object({
+			description: Type.String({ 
+				description: "High-level project description to analyze and plan" 
+			}),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			const { description } = params as { description: string };
+
+			try {
+				const result = await createPlanFiles(description);
+
+				const summary = `**Project orchestration completed!**
+
+**Generated files:**
+- Specification: ${result.specFile}
+- Task list: ${result.todoFile}
+
+**Project:** ${result.plan.title}
+**Tasks created:** ${result.plan.tasks.length}
+**Goals identified:** ${result.plan.goals.length}
+**Requirements:** ${result.plan.requirements.length}
+
+**Next steps:**
+1. Review and refine the specification
+2. Update task details in the TODO file  
+3. Begin implementation following the task order
+4. Mark tasks as completed by updating the TODO file
+
+Files are saved in .phi/plans/ directory.`;
+
+				return {
+					content: [{ type: "text", text: summary }],
+					details: {
+						specFile: result.specFile,
+						todoFile: result.todoFile,
+						taskCount: result.plan.tasks.length,
+						project: result.plan.title
+					}
+				};
+
+			} catch (error) {
+				return {
+					content: [{ type: "text", text: `Orchestration failed: ${error}` }],
+					details: { error: String(error) }
+				};
+			}
+		},
+	});
+
+	/**
+	 * /plan command - Interactive project planning
+	 */
+	pi.registerCommand("plan", {
+		description: "Create a structured project plan from a description",
+		handler: async (args, ctx) => {
+			const description = args.trim();
+
+			if (!description) {
+				ctx.ui.notify("Usage: /plan <project description>", "warning");
+				return;
+			}
+
+			try {
+				ctx.ui.notify("Creating project plan...", "info");
+				
+				const result = await createPlanFiles(description);
+
+				const message = `✅ Project plan created!
+
+📋 **${result.plan.title}**
+📁 Spec: ${result.specFile}
+📋 TODO: ${result.todoFile}
+🎯 ${result.plan.tasks.length} tasks identified
+
+Open .phi/plans/ to review your project files.`;
+
+				ctx.ui.notify(message, "info");
+
+			} catch (error) {
+				ctx.ui.notify(`Failed to create plan: ${error}`, "error");
+			}
+		},
+	});
+
+	/**
+	 * /plans command - List existing plans
+	 */
+	pi.registerCommand("plans", {
+		description: "List existing project plans",
+		handler: async (_args, ctx) => {
+			try {
+				const files = await readdir(plansDir);
+				const specFiles = files.filter(f => f.startsWith('spec-') && f.endsWith('.md'));
+				const todoFiles = files.filter(f => f.startsWith('todo-') && f.endsWith('.md'));
+
+				if (specFiles.length === 0) {
+					ctx.ui.notify("No project plans found. Use /plan <description> to create one.", "info");
+					return;
+				}
+
+				let message = `📁 **Project Plans** (${specFiles.length} found)\n\n`;
+				
+				// Group by timestamp
+				const planPairs: Array<{ spec: string; todo: string; timestamp: string }> = [];
+				
+				for (const specFile of specFiles) {
+					const timestamp = specFile.replace('spec-', '').replace('.md', '');
+					const todoFile = `todo-${timestamp}.md`;
+					
+					if (todoFiles.includes(todoFile)) {
+						planPairs.push({ spec: specFile, todo: todoFile, timestamp });
+					}
+				}
+
+				planPairs.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+
+				for (const pair of planPairs) {
+					// Try to read spec title
+					try {
+						const specContent = await readFile(join(plansDir, pair.spec), 'utf-8');
+						const titleMatch = specContent.match(/^# (.+)$/m);
+						const title = titleMatch ? titleMatch[1] : pair.spec;
+						
+						const date = pair.timestamp.replace(/_/g, ' ').replace(/-/g, ':');
+						message += `📋 **${title}**\n`;
+						message += `   📄 ${pair.spec}\n`;
+						message += `   ✅ ${pair.todo}\n`;
+						message += `   🕒 ${date}\n\n`;
+					} catch {
+						message += `📋 ${pair.spec} / ${pair.todo}\n\n`;
+					}
+				}
+
+				ctx.ui.notify(message, "info");
+
+			} catch (error) {
+				ctx.ui.notify(`Failed to list plans: ${error}`, "error");
+			}
+		},
+	});
+}