@phi-code-admin/phi-code 0.74.0 → 0.74.2

package/extensions/phi/orchestrator.ts

@@ -16,12 +16,24 @@
  *   /plans  — List plans and their execution status
  */
 
+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";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 
+// ─── Types ───────────────────────────────────────────────────────────────
+
+interface TaskDef {
+	title: string;
+	description: string;
+	agent?: string;
+	priority?: string;
+	dependencies?: number[];
+	subtasks?: string[];
+}
+
 // ─── Extension ───────────────────────────────────────────────────────────
 
 export default function orchestratorExtension(pi: ExtensionAPI) {
@@ -35,6 +47,161 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 		return new Date().toISOString().replace(/[:.]/g, "-").replace("T", "_").slice(0, 19);
 	}
 
+	// ─── Plan File Generators ────────────────────────────────────────
+
+	function generateSpec(p: {
+		title: string; description: string; goals: string[]; requirements: string[];
+		architecture?: string[]; constraints?: string[]; successCriteria?: string[]; tasks: TaskDef[];
+	}): string {
+		let spec = `# ${p.title}\n\n`;
+		spec += `**Created:** ${new Date().toLocaleString()}\n\n`;
+		spec += `## Description\n\n${p.description}\n\n`;
+		spec += `## Goals\n\n`;
+		p.goals.forEach((g, i) => { spec += `${i + 1}. ${g}\n`; });
+		spec += "\n## Requirements\n\n";
+		p.requirements.forEach(r => { spec += `- ${r}\n`; });
+		spec += "\n";
+		if (p.architecture?.length) {
+			spec += `## Architecture\n\n`;
+			p.architecture.forEach(a => { spec += `- ${a}\n`; });
+			spec += "\n";
+		}
+		if (p.constraints?.length) {
+			spec += `## Constraints\n\n`;
+			p.constraints.forEach(c => { spec += `- ${c}\n`; });
+			spec += "\n";
+		}
+		if (p.successCriteria?.length) {
+			spec += `## Success Criteria\n\n`;
+			p.successCriteria.forEach(s => { spec += `- [ ] ${s}\n`; });
+			spec += "\n";
+		}
+		spec += `## Task Overview\n\n| # | Task | Agent | Priority | Dependencies |\n|---|------|-------|----------|-------------|\n`;
+		p.tasks.forEach((t, i) => {
+			const deps = t.dependencies?.map(d => `#${d}`).join(", ") || "—";
+			spec += `| ${i + 1} | ${t.title} | ${t.agent || "code"} | ${t.priority || "medium"} | ${deps} |\n`;
+		});
+		spec += `\n---\n*Generated by Phi Code Orchestrator*\n`;
+		return spec;
+	}
+
+	function generateTodo(title: string, tasks: TaskDef[]): string {
+		let todo = `# TODO: ${title}\n\n`;
+		todo += `**Created:** ${new Date().toLocaleString()}\n`;
+		todo += `**Tasks:** ${tasks.length}\n**Status:** executing\n\n`;
+		tasks.forEach((t, i) => {
+			const agentTag = t.agent ? ` [${t.agent}]` : "";
+			const prioTag = t.priority === "high" ? " 🔴" : t.priority === "low" ? " 🟢" : " 🟡";
+			const depsTag = t.dependencies?.length ? ` (after #${t.dependencies.join(", #")})` : "";
+			todo += `## Task ${i + 1}: ${t.title}${prioTag}${agentTag}${depsTag}\n\n- [ ] ${t.description}\n`;
+			if (t.subtasks) t.subtasks.forEach(st => { todo += `  - [ ] ${st}\n`; });
+			todo += "\n";
+		});
+		todo += `---\n\n## Progress\n\n- Total: ${tasks.length} tasks\n`;
+		todo += `- High priority: ${tasks.filter(t => t.priority === "high").length}\n`;
+		todo += `- Agents: ${[...new Set(tasks.map(t => t.agent || "code"))].join(", ")}\n`;
+		return todo;
+	}
+
+	// ─── Orchestrate Tool — Structured planning with prompt-architect pattern ───
+
+	pi.registerTool({
+		name: "orchestrate",
+		label: "Project Orchestrator",
+		description: "Create a structured project plan with spec, todo, and task breakdown. Forces the model to decompose the project into goals, requirements, architecture, constraints, and success criteria before execution.",
+		promptSnippet: "Plan + structure projects using the prompt-architect pattern. Each task gets [CONTEXT] → [TASK] → [FORMAT] → [CONSTRAINTS].",
+		promptGuidelines: [
+			// NOTE: The old guideline "When asked to plan or build a project, call the orchestrate tool"
+			// was REMOVED because it hijacked the /plan command flow. The orchestrate tool is now
+			// only called explicitly or when the model decides structured planning is needed outside of /plan.
+			"IMPORTANT: Do NOT call orchestrate during /plan orchestration phases. The /plan command handles its own workflow.",
+			"Structure each task description using the prompt-architect pattern: [CONTEXT] what exists and why → [TASK] what to do specifically → [FORMAT] expected output → [CONSTRAINTS] rules and limitations.",
+			"Assign agent types strategically: 'explore' (read-only analysis), 'plan' (architecture), 'code' (implementation), 'test' (write+run tests), 'review' (quality audit).",
+			"Set dependencies to maximize parallelism: tasks without dependencies run simultaneously.",
+			"Set priority=high for critical-path tasks, medium for standard work, low for nice-to-haves.",
+		],
+		parameters: Type.Object({
+			title: Type.String({ description: "Concise project title" }),
+			description: Type.String({ description: "Full project description: what to build, why, and any relevant context" }),
+			goals: Type.Union([Type.Array(Type.String()), Type.String()], { description: "Measurable project goals (what success looks like)" }),
+			requirements: Type.Union([Type.Array(Type.String()), Type.String()], { description: "Technical and functional requirements" }),
+			architecture: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "Architecture decisions, tech stack choices, trade-offs" })),
+			tasks: Type.Array(
+				Type.Object({
+					title: Type.String({ description: "Clear, action-oriented task title" }),
+					description: Type.String({ description: "SELF-CONTAINED task description. Include ALL context the sub-agent needs." }),
+					agent: Type.Optional(Type.String({ description: "Agent type: explore, plan, code, test, review" })),
+					priority: Type.Optional(Type.String({ description: "high, medium, low" })),
+					dependencies: Type.Optional(Type.Array(Type.Number(), { description: "Task numbers this depends on (1-indexed)" })),
+					subtasks: Type.Optional(Type.Array(Type.String(), { description: "Specific sub-steps within this task" })),
+				}),
+				{ description: "Ordered list of tasks" }
+			),
+			constraints: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "Hard constraints: things to avoid, rules" })),
+			successCriteria: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "How to verify the project is complete" })),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			// Block if /plan orchestration is active — prevent hijacking
+			if (orchestrationActive) {
+				return {
+					content: [{ type: "text", text: "⚠️ Orchestration is already active via /plan. Do NOT call orchestrate during /plan phases. Follow the phase instructions instead." }],
+				};
+			}
+
+			const raw = params as any;
+
+			// Normalize string fields to arrays
+			const toArray = (v: any): string[] => {
+				if (!v) return [];
+				if (Array.isArray(v)) return v;
+				if (typeof v === "string") return v.split("\n").map((s: string) => s.replace(/^[-•*]\s*/, "").trim()).filter(Boolean);
+				return [];
+			};
+
+			const p = {
+				title: raw.title as string,
+				description: raw.description as string,
+				goals: toArray(raw.goals),
+				requirements: toArray(raw.requirements),
+				architecture: raw.architecture ? toArray(raw.architecture) : undefined,
+				tasks: raw.tasks as TaskDef[],
+				constraints: raw.constraints ? toArray(raw.constraints) : undefined,
+				successCriteria: raw.successCriteria ? toArray(raw.successCriteria) : undefined,
+			};
+
+			try {
+				await ensurePlansDir();
+				const ts = timestamp();
+				const specFile = `spec-${ts}.md`;
+				const todoFile = `todo-${ts}.md`;
+
+				// Generate and write structured plan files
+				const spec = generateSpec(p);
+				const todo = generateTodo(p.title, p.tasks);
+				await writeFile(join(plansDir, specFile), spec, "utf-8");
+				await writeFile(join(plansDir, todoFile), todo, "utf-8");
+
+				const summary = `📋 **Project "${p.title}" — Structured plan created!**\n\n` +
+					`**Spec:** \`${specFile}\` | **Todo:** \`${todoFile}\`\n\n` +
+					`**Goals:** ${p.goals.length} | **Requirements:** ${p.requirements.length} | **Tasks:** ${p.tasks.length}\n\n` +
+					`The spec and todo files are ready in \`.phi/plans/\`. ` +
+					`Use \`/plan ${p.description.slice(0, 100)}\` to execute with the 5-phase orchestrator, ` +
+					`or work through the tasks manually.`;
+
+				return {
+					content: [{ type: "text", text: summary }],
+					details: { specFile, todoFile, taskCount: p.tasks.length },
+				};
+			} catch (error) {
+				return {
+					content: [{ type: "text", text: `Orchestration failed: ${error}` }],
+					details: { error: String(error) },
+				};
+			}
+		},
+	});
+
 	// ─── Orchestration State ─────────────────────────────────────────
 
 	interface AgentDef {
@@ -119,7 +286,10 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 
 		const ts = timestamp();
 		// Inject runtime info so agents can adapt to the host OS
-		const runtimeInfo = `\n\nRuntime: ${process.platform} (${process.arch})`;
+		const shellNote = process.platform === 'win32'
+			? `\nShell: bash (Git Bash), NOT cmd.exe. Always use Unix syntax: rm not del, test -f not if exist, / not \\\\`
+			: '';
+		const runtimeInfo = `\n\nRuntime: ${process.platform} (${process.arch})${shellNote}`;
 
 		return [
 			{
@@ -144,7 +314,7 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
    - Requirements: specific features needed
    - Tech decisions: frameworks, patterns to use
    - Constraints: what to NOT break
-5. Write your findings to \`.phi/plans/explore-${ts}.md\`
+5. **MANDATORY:** Write your findings to \`.phi/plans/explore-${ts}.md\` using the \`write\` tool. This file is READ by Phase 2 PLAN — if you skip it, the plan agent has no context. Do NOT skip this step.
 
 **LAST ACTION (MANDATORY):** Call \`memory_write\` to save your exploration findings for downstream agents.
 
@@ -261,6 +431,8 @@ Before finishing, use \`memory_write\` to save your plan summary with relevant t
 
 After implementation, use \`memory_write\` to save a summary of what was built, patterns used, and any issues encountered.
 
+**Ontology update:** Use \`ontology_add\` to update the project status (e.g., entity "implementation" type "Phase" with properties {status: "complete", files: "N"}) and add a relation to the project entity.
+
 **CRITICAL RULES:**
 - Write ONE file per tool call — NEVER combine multiple files in a single response
 - Keep each file under 500 lines. If longer, split into modules
@@ -318,7 +490,9 @@ After implementation, use \`memory_write\` to save a summary of what was built,
 
 **Anti-loop rule:** If the SAME test fails 3 times in a row with the same error after your fixes, STOP trying to fix it. Write the failure in your test report as "UNRESOLVED" and move on. Do not waste more than 3 iterations on the same issue.
 
-After testing, use \`memory_write\` to save test results, bugs found, and lessons learned.` + runtimeInfo,
+After testing, use \`memory_write\` to save test results, bugs found, and lessons learned.
+
+**Ontology update:** Use \`ontology_add\` to update the project status (e.g., entity "test-results" type "Phase" with properties {passed: "N", failed: "M", coverage: "X%"}) and add a relation to the project entity.` + runtimeInfo,
 			},
 			{
 				key: "review", label: "🔍 Phase 5 — REVIEW", model: review.preferred, fallback: review.fallback,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phi-code-admin/phi-code",
-  "version": "0.74.0",
+  "version": "0.74.2",
   "description": "Coding agent CLI with read, bash, edit, write tools and session management",
   "type": "module",
   "piConfig": {