pi-mission-control 0.0.0-dev

package/src/tools/add-task.ts

@@ -0,0 +1,121 @@
+/**
+ * add_task tool
+ * 
+ * Agent tool to add a new task to a phase.
+ * Auto-generates task_id from phase prefix ("phase1-task1", "phase1-task2", ...).
+ * Sets status to "pending".
+ * 
+ * Used by: mission-pm skill
+ */
+
+import {
+  readState,
+  readRun,
+  writeRun,
+  findPhase,
+  generateTaskId,
+  createTask,
+  addTaskToRun,
+  ensureDir,
+  getTaskDir
+} from "../state.js";
+
+export interface AddTaskParams {
+  phase_id: string;
+  name: string;
+  file: string;
+}
+
+export interface AddTaskResult {
+  success: boolean;
+  message: string;
+  taskId: string | null;
+  errors: string[];
+}
+
+/**
+ * Add a task to a phase in the active mission run
+ * 
+ * @param params.phase_id - ID of the phase to add task to (e.g., "phase1")
+ * @param params.name - Human-readable task name (e.g., "Setup DB Schema")
+ * @param params.file - Path to task contract file
+ * @returns Result with generated task_id
+ */
+export function addTask(params: AddTaskParams): AddTaskResult {
+  const result: AddTaskResult = {
+    success: false,
+    message: "",
+    taskId: null,
+    errors: []
+  };
+
+  try {
+    // Validate parameters
+    if (!params.phase_id || params.phase_id.trim() === "") {
+      result.errors.push("Phase ID is required");
+      result.message = "Failed to add task: phase_id is required";
+      return result;
+    }
+
+    if (!params.name || params.name.trim() === "") {
+      result.errors.push("Task name is required");
+      result.message = "Failed to add task: name is required";
+      return result;
+    }
+
+    if (!params.file || params.file.trim() === "") {
+      result.errors.push("Task file is required");
+      result.message = "Failed to add task: file is required";
+      return result;
+    }
+
+    // Get active run
+    const state = readState();
+    if (!state.active_run_id) {
+      result.errors.push("No active run");
+      result.message = "Failed to add task: no active mission run";
+      return result;
+    }
+
+    // Read run.json
+    const run = readRun(state.active_run_id);
+    if (!run) {
+      result.errors.push(`Run not found: ${state.active_run_id}`);
+      result.message = "Failed to add task: run not found";
+      return result;
+    }
+
+    // Find phase
+    const phase = findPhase(run, params.phase_id.trim());
+    if (!phase) {
+      result.errors.push(`Phase not found: ${params.phase_id}`);
+      result.message = "Failed to add task: phase not found";
+      return result;
+    }
+
+    // Generate task ID
+    const taskId = generateTaskId(phase);
+
+    // Create task
+    const task = createTask(taskId, params.name.trim(), params.file.trim());
+
+    // Add to run
+    const updatedRun = addTaskToRun(run, params.phase_id.trim(), task);
+    writeRun(updatedRun);
+
+    // Create task directory
+    const taskDir = getTaskDir(state.active_run_id, taskId);
+    ensureDir(taskDir);
+
+    result.success = true;
+    result.taskId = taskId;
+    result.message = `Task added: ${taskId} - ${params.name}`;
+
+  } catch (error) {
+    result.success = false;
+    result.message = `Error adding task: ${error instanceof Error ? error.message : String(error)}`;
+    result.errors.push(String(error));
+  }
+
+  return result;
+}

package/src/tools/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Tools index - exports all mission-control tools
+ */
+
+// Re-export isScaffolded from state
+export { isScaffolded } from "../state.js";
+
+// Command-only tools (called by /mission, not exposed to agents)
+export { missionScaffold, type ScaffoldResult } from "./scaffold.js";
+export { missionInit, type InitOptions, type InitResult } from "./init.js";
+
+// Agent tools (registered for LLM use)
+export { addPhase, type AddPhaseParams, type AddPhaseResult } from "./add-phase.js";
+export { addTask, type AddTaskParams, type AddTaskResult } from "./add-task.js";
+export { updatePhase, type UpdatePhaseParams, type UpdatePhaseResult } from "./update-phase.js";
+export { updateTask, type UpdateTaskParams, type UpdateTaskResult } from "./update-task.js";
+export { missionComplete, type MissionCompleteParams, type MissionCompleteResult } from "./mission-complete.js";
+export { missionResume, type MissionResumeParams, type MissionResumeResult } from "./mission-resume.js";

package/src/tools/init.ts

@@ -0,0 +1,109 @@
+/**
+ * mission_init tool
+ * 
+ * Creates a new mission run directory with run.json and updates state.json.
+ * Called when user clicks "Init new mission" button.
+ * 
+ * This is a command-only tool (not exposed to agents).
+ */
+
+import {
+  generateRunId,
+  createInitialRun,
+  createRunStructure,
+  writeRun,
+  updateState,
+  readState,
+  writeText,
+  getRunDir,
+  isScaffolded
+} from "../state.js";
+
+export interface InitOptions {
+  runId?: string;
+  phase?: string;
+  statusMessage?: string;
+}
+
+export interface InitResult {
+  success: boolean;
+  message: string;
+  runId: string | null;
+  runDir: string | null;
+  errors: string[];
+}
+
+/**
+ * Initialize a new mission run
+ * 
+ * Creates:
+ * - run directory: .pi/mission-control/runs/<run-id>/
+ * - run.json with initial structure
+ * - empty artifact files (00-requirements.md, etc.)
+ * - tasks directory
+ * 
+ * Updates:
+ * - state.json with active_run_id
+ */
+export function missionInit(options: InitOptions = {}): InitResult {
+  const result: InitResult = {
+    success: false,
+    message: "",
+    runId: null,
+    runDir: null,
+    errors: []
+  };
+
+  try {
+    // Check if scaffolding exists
+    if (!isScaffolded()) {
+      result.errors.push("Mission Control not scaffolded. Run scaffold first.");
+      result.message = "Initialization failed: scaffolding required";
+      return result;
+    }
+
+    // Check if there's already an active run
+    const currentState = readState();
+    if (currentState.active_run_id) {
+      result.errors.push(`Active run exists: ${currentState.active_run_id}. Complete or resume it first.`);
+      result.message = "Initialization failed: another run is active";
+      return result;
+    }
+
+    // Generate run ID
+    const runId = options.runId || generateRunId();
+    result.runId = runId;
+
+    // Create run structure
+    createRunStructure(runId);
+    result.runDir = getRunDir(runId);
+
+    // Create initial run.json
+    const run = createInitialRun(runId);
+    writeRun(run);
+
+    // Create empty artifact files
+    const runDir = getRunDir(runId);
+    writeText(`${runDir}/00-requirements.md`, `# Requirements\n\nRun ID: ${runId}\nCreated: ${run.started_at}\n\n<!-- Requirements will be written here by mission-orchestrator skill -->\n`);
+    writeText(`${runDir}/01-architecture.md`, `# Architecture\n\nRun ID: ${runId}\n\n<!-- Architecture will be written here by mission-tech-lead skill -->\n`);
+    writeText(`${runDir}/02-validation.md`, `# Validation Contract\n\nRun ID: ${runId}\n\n<!-- Validation criteria will be written here by mission-tech-lead skill -->\n`);
+    writeText(`${runDir}/short_term_memory.md`, `# Short-term Memory\n\nRun ID: ${runId}\n\n<!-- Learnings from this run will be accumulated here -->\n`);
+
+    // Update state.json
+    updateState({
+      active_run_id: runId,
+      current_phase: options.phase || "research",
+      current_status_message: options.statusMessage || "Mission initialized - waiting for requirements"
+    });
+
+    result.success = true;
+    result.message = `Mission initialized: ${runId}`;
+
+  } catch (error) {
+    result.success = false;
+    result.message = `Initialization error: ${error instanceof Error ? error.message : String(error)}`;
+    result.errors.push(String(error));
+  }
+
+  return result;
+}

package/src/tools/mission-complete.ts

@@ -0,0 +1,118 @@
+/**
+ * mission_complete tool
+ * 
+ * Agent tool to mark a mission run as complete.
+ * Sets run.json status to "done" and finish_at timestamp.
+ * Clears active_run_id from state.json.
+ * 
+ * Used by: mission-orchestrator skill
+ */
+
+import {
+  readState,
+  readRun,
+  writeRun,
+  updateState,
+  getTimestamp,
+  RunStatus
+} from "../state.js";
+
+export interface MissionCompleteParams {
+  run_id: string;
+}
+
+export interface MissionCompleteResult {
+  success: boolean;
+  message: string;
+  runId: string | null;
+  previousStatus: RunStatus | null;
+  newStatus: RunStatus;
+  finishAt: string;
+  errors: string[];
+}
+
+/**
+ * Mark a mission run as complete
+ * 
+ * @param params.run_id - ID of the run to complete
+ * @returns Result with completion info
+ */
+export function missionComplete(params: MissionCompleteParams): MissionCompleteResult {
+  const result: MissionCompleteResult = {
+    success: false,
+    message: "",
+    runId: null,
+    previousStatus: null,
+    newStatus: "done",
+    finishAt: "",
+    errors: []
+  };
+
+  try {
+    // Validate parameters
+    if (!params.run_id || params.run_id.trim() === "") {
+      result.errors.push("Run ID is required");
+      result.message = "Failed to complete mission: run_id is required";
+      return result;
+    }
+
+    const runId = params.run_id.trim();
+    result.runId = runId;
+
+    // Read the run
+    const run = readRun(runId);
+    if (!run) {
+      result.errors.push(`Run not found: ${runId}`);
+      result.message = "Failed to complete mission: run not found";
+      return result;
+    }
+
+    result.previousStatus = run.status;
+
+    // Check if run is already completed
+    if (run.status === "done") {
+      result.success = true;
+      result.message = `Mission ${runId} is already complete`;
+      result.finishAt = run.finish_at || getTimestamp();
+      return result;
+    }
+
+    // Check if run is in a state that can be completed
+    if (run.status === "failed") {
+      result.errors.push(`Run ${runId} has failed status and cannot be marked complete`);
+      result.message = "Failed to complete mission: run has failed status";
+      return result;
+    }
+
+    const now = getTimestamp();
+    result.finishAt = now;
+
+    // Update run.json
+    const updatedRun = {
+      ...run,
+      status: "done" as RunStatus,
+      finish_at: now
+    };
+    writeRun(updatedRun);
+
+    // Clear active_run_id from state.json if it matches
+    const state = readState();
+    if (state.active_run_id === runId) {
+      updateState({
+        active_run_id: null,
+        current_phase: "idle",
+        current_status_message: "Mission complete"
+      });
+    }
+
+    result.success = true;
+    result.message = `Mission ${runId} marked as complete`;
+
+  } catch (error) {
+    result.success = false;
+    result.message = `Error completing mission: ${error instanceof Error ? error.message : String(error)}`;
+    result.errors.push(String(error));
+  }
+
+  return result;
+}

package/src/tools/mission-resume.ts

@@ -0,0 +1,119 @@
+/**
+ * mission_resume tool
+ * 
+ * Agent tool to resume a previously created mission run.
+ * Sets state.json active_run_id to the specified run_id.
+ * 
+ * Used by: mission-orchestrator skill (when user asks to resume)
+ */
+
+import {
+  readState,
+  readRun,
+  updateState,
+  RunStatus
+} from "../state.js";
+
+export interface MissionResumeParams {
+  run_id: string;
+  phase?: string;
+  statusMessage?: string;
+}
+
+export interface MissionResumeResult {
+  success: boolean;
+  message: string;
+  runId: string | null;
+  runStatus: RunStatus | null;
+  previousActiveRunId: string | null;
+  errors: string[];
+}
+
+/**
+ * Resume a mission run
+ * 
+ * Sets the specified run as the active run in state.json.
+ * Fails if there's already a different active run.
+ * 
+ * @param params.run_id - ID of the run to resume
+ * @param params.phase - Optional phase to set as current (defaults to run's current state)
+ * @param params.statusMessage - Optional status message
+ * @returns Result with resume info
+ */
+export function missionResume(params: MissionResumeParams): MissionResumeResult {
+  const result: MissionResumeResult = {
+    success: false,
+    message: "",
+    runId: null,
+    runStatus: null,
+    previousActiveRunId: null,
+    errors: []
+  };
+
+  try {
+    // Validate parameters
+    if (!params.run_id || params.run_id.trim() === "") {
+      result.errors.push("Run ID is required");
+      result.message = "Failed to resume mission: run_id is required";
+      return result;
+    }
+
+    const runId = params.run_id.trim();
+    result.runId = runId;
+
+    // Read current state
+    const state = readState();
+    result.previousActiveRunId = state.active_run_id;
+
+    // Check if there's already a different active run
+    if (state.active_run_id && state.active_run_id !== runId) {
+      result.errors.push(`Another run is active: ${state.active_run_id}. Complete or pause it first.`);
+      result.message = "Failed to resume mission: another run is active";
+      return result;
+    }
+
+    // Read the run to verify it exists
+    const run = readRun(runId);
+    if (!run) {
+      result.errors.push(`Run not found: ${runId}`);
+      result.message = "Failed to resume mission: run not found";
+      return result;
+    }
+
+    result.runStatus = run.status;
+
+    // Check if run is in a resumable state
+    if (run.status === "done") {
+      result.errors.push(`Run ${runId} is already complete`);
+      result.message = "Failed to resume mission: run is already complete";
+      return result;
+    }
+
+    // Determine current phase
+    let currentPhase = params.phase || "execution";
+    if (!params.phase && run.phases.length > 0) {
+      // Find the first non-done phase
+      const activePhase = run.phases.find(p => p.status !== "done" && p.status !== "removed");
+      if (activePhase) {
+        currentPhase = activePhase.id;
+      }
+    }
+
+    // Update state.json
+    updateState({
+      active_run_id: runId,
+      current_phase: currentPhase,
+      current_status_message: params.statusMessage || `Resumed mission: ${runId}`
+    });
+
+    result.success = true;
+    result.message = `Mission resumed: ${runId}`;
+
+  } catch (error) {
+    result.success = false;
+    result.message = `Error resuming mission: ${error instanceof Error ? error.message : String(error)}`;
+    result.errors.push(String(error));
+  }
+
+  return result;
+}

package/src/tools/scaffold.ts

@@ -0,0 +1,167 @@
+/**
+ * mission_scaffold tool
+ * 
+ * First-time setup tool - copies bundled worker/auditor agents and skills
+ * into project .pi dirs and creates mission-control directory structure.
+ * 
+ * This is a command-only tool (not exposed to agents).
+ */
+
+import * as path from "path";
+import * as fs from "fs";
+import { fileURLToPath } from "url";
+import {
+  getProjectRoot,
+  getMissionControlDir,
+  getMemoryDir,
+  getRunsDir,
+  ensureDir,
+  copyDir,
+  fileExists,
+  writeJson,
+  defaultState,
+  isScaffolded
+} from "../state.js";
+
+export interface ScaffoldResult {
+  success: boolean;
+  message: string;
+  created: string[];
+  skipped: string[];
+  errors: string[];
+}
+
+const packageRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/**
+ * Get the bundled agents directory path (within the npm package)
+ */
+function getBundledAgentsDir(): string {
+  return path.join(packageRoot, "agents");
+}
+
+/**
+ * Get the bundled skills directory path (within the npm package)
+ */
+function getBundledSkillsDir(): string {
+  return path.join(packageRoot, "skills");
+}
+
+/**
+ * Get the bundled templates directory path (within the npm package)
+ */
+function getBundledTemplatesDir(): string {
+  return path.join(packageRoot, "templates");
+}
+
+/**
+ * Get target paths in the project
+ */
+function getTargetPaths() {
+  const projectRoot = getProjectRoot();
+  return {
+    agents: path.join(projectRoot, ".pi", "agents"),
+    skills: path.join(projectRoot, ".pi", "skills"),
+    missionControl: getMissionControlDir(),
+    memory: getMemoryDir(),
+    runs: getRunsDir()
+  };
+}
+
+/**
+ * Scaffold the mission-control environment
+ * 
+ * Copies bundled worker/auditor agents and skills to project .pi dirs and creates
+ * the mission-control directory structure. Non-destructive - 
+ * skips existing files rather than overwriting.
+ */
+export function missionScaffold(): ScaffoldResult {
+  const result: ScaffoldResult = {
+    success: true,
+    message: "",
+    created: [],
+    skipped: [],
+    errors: []
+  };
+
+  try {
+    const bundledDirs = {
+      agents: getBundledAgentsDir(),
+      skills: getBundledSkillsDir(),
+      templates: getBundledTemplatesDir()
+    };
+
+    const targetPaths = getTargetPaths();
+
+    // Verify bundled directories exist
+    for (const [name, dirPath] of Object.entries(bundledDirs)) {
+      if (!fileExists(dirPath)) {
+        result.errors.push(`Bundled ${name} directory not found: ${dirPath}`);
+      }
+    }
+
+    if (result.errors.length > 0) {
+      result.success = false;
+      result.message = "Scaffolding failed: bundled resources not found";
+      return result;
+    }
+
+    // Create base directory structure
+    ensureDir(targetPaths.missionControl);
+    ensureDir(targetPaths.memory);
+    ensureDir(targetPaths.runs);
+    result.created.push(".pi/mission-control/");
+    result.created.push(".pi/mission-control/memory/");
+    result.created.push(".pi/mission-control/runs/");
+
+    // Create state.json if it doesn't exist
+    const statePath = path.join(targetPaths.missionControl, "state.json");
+    if (!fileExists(statePath)) {
+      writeJson(statePath, defaultState);
+      result.created.push(".pi/mission-control/state.json");
+    } else {
+      result.skipped.push(".pi/mission-control/state.json (already exists)");
+    }
+
+    // Copy worker/auditor agents (skip existing files)
+    const agentsCopied = copyDir(bundledDirs.agents, targetPaths.agents, true);
+    if (agentsCopied > 0) {
+      result.created.push(`.pi/agents/ (${agentsCopied} files copied)`);
+    } else {
+      result.skipped.push(".pi/agents/ (all files already exist)");
+    }
+
+    // Copy skills (skip existing files)
+    const skillsCopied = copyDir(bundledDirs.skills, targetPaths.skills, true);
+    if (skillsCopied > 0) {
+      result.created.push(`.pi/skills/ (${skillsCopied} files copied)`);
+    } else {
+      result.skipped.push(".pi/skills/ (all files already exist)");
+    }
+
+    // Create long_term.md if it doesn't exist
+    const longTermPath = path.join(targetPaths.memory, "long_term.md");
+    if (!fileExists(longTermPath)) {
+      fs.writeFileSync(
+        longTermPath,
+        "# Long-term Memory\n\nDistilled knowledge from past missions.\n\n## Repo Conventions\n\n## Tooling Quirks\n\n## Architecture Decisions\n\n## Common Failures\n\n## Performance Notes\n",
+        "utf-8"
+      );
+      result.created.push(".pi/mission-control/memory/long_term.md");
+    } else {
+      result.skipped.push(".pi/mission-control/memory/long_term.md (already exists)");
+    }
+
+    result.success = true;
+    result.message = "Mission Control scaffolding complete";
+
+  } catch (error) {
+    result.success = false;
+    result.message = `Scaffolding error: ${error instanceof Error ? error.message : String(error)}`;
+    result.errors.push(String(error));
+  }
+
+  return result;
+}
+
+