takomi 2.1.9 → 2.1.11

package/.pi/extensions/takomi-context-manager/prompt-rewriter.ts

@@ -2,25 +2,40 @@ import type { CandidateContext, ContextManagerConfig, SkillRecord } from "./type
 import { renderCandidateHint } from "./context-router";
 import { sortedSkills } from "./skill-registry";
 
-function renderSkillIndex(skills: SkillRecord[]): string {
-  if (skills.length === 0) return "Skills: none discovered.";
-  return `Skills: ${skills.length} discovered. Use skill_index only when the task may need a skill.`;
+function renderSkillNames(skills: SkillRecord[]): string {
+  return ["Available skills (names only):", ...skills.map((skill) => `- ${skill.name}`)].join("\n");
 }
 
-function renderProgressiveRule(): string {
+function renderSkillDisplay(skills: SkillRecord[], candidates: CandidateContext[], config: ContextManagerConfig): string {
+  const mode = config.skillDisplay.mode;
+  const countLine = skills.length === 0 ? "Skills: none discovered." : `Skills: ${skills.length} available.`;
+
+  if (mode === "hidden") return `${countLine} Use skill_index if this task may need a skill.`;
+  if (mode === "all-names") return skills.length === 0 ? countLine : renderSkillNames(skills);
+  if (mode === "auto" && skills.length <= config.skillDisplay.maxVisibleSkillNames) {
+    return skills.length === 0 ? countLine : renderSkillNames(skills);
+  }
+
+  const candidateHint = renderCandidateHint(candidates);
+  return [countLine, candidateHint || "Use skill_index if a specialized skill may help."].join("\n");
+}
+
+function renderProgressiveRule(config: ContextManagerConfig): string {
+  if (!config.skillDisplay.alwaysShowToolInstructions) return "";
   return [
     "Skill loading:",
     "- Skills are optional capability packs that give you special instructions/tools for specialized, repetitive tasks.",
     "- Do not preload skill descriptions into the prompt.",
-    "- When doing specialized work, you may check whether a suited skill exists with skill_index.",
+    "- Use skill_index to view all skill names when needed.",
     "- For uncertain matches, request skill_manifest for likely skills; manifests include descriptions and locations.",
     "- If a skill is clearly relevant or the user names it directly, use skill_load without requesting a manifest first.",
     "- Load full skill instructions only for skills you will actually use.",
     "",
     "Policy loading:",
     "- Model/subagent/lifecycle policies are lazy-loaded policy packs.",
-    "- Use policy_manifest to inspect available policies.",
-    "- Use policy_load before sensitive tools such as takomi_subagent.",
+    "- The active routing policy may come from the project or the bundled Takomi harness default.",
+    "- Use policy_manifest or policy_load when you need to inspect or quote a policy explicitly.",
+    "- If takomi_subagent is blocked for missing policy context, the gate has already loaded the required policy for this session; retry the tool call and follow it.",
   ].join("\n");
 }
 
@@ -28,7 +43,7 @@ function compactHeavyPolicyBlocks(prompt: string, config: ContextManagerConfig):
   let next = prompt;
   const removedSections: string[] = [];
   if (config.promptCompaction.compactModelRouting) {
-    const modelRoutingRegex = /Project Takomi model routing policy is active\. Apply it when choosing parent\/subagent models and escalation levels:\s*\n\n# Takomi Model Routing Policy[\s\S]*?(?=\nAvailable model context from Pi registry:)/;
+    const modelRoutingRegex = /(Project|Bundled) Takomi model routing policy is active\. Apply it when choosing parent\/subagent models and escalation levels:\s*\n\n# Takomi Model Routing Policy[\s\S]*?(?=\nAvailable model context from Pi registry:)/;
     if (modelRoutingRegex.test(next)) {
       next = next.replace(modelRoutingRegex, [
         "Project Takomi model routing policy is available as a lazy-loaded policy pack.",
@@ -60,7 +75,11 @@ export function rewritePrompt(systemPrompt: string, skills: Map<string, SkillRec
   let changed = false;
 
   if (config.promptCompaction.compactSkillDescriptions) {
-    const replacement = [renderSkillIndex(sortedSkills(skills)), renderProgressiveRule(), renderCandidateHint(candidates)].filter(Boolean).join("\n\n");
+    const sorted = sortedSkills(skills);
+    const replacement = [
+      renderSkillDisplay(sorted, candidates, config),
+      renderProgressiveRule(config),
+    ].filter(Boolean).join("\n\n");
     const skillBlockRegex = /<available_skills>[\s\S]*?<\/available_skills>/i;
     if (!skillBlockRegex.test(next)) {
       warnings.push("No <available_skills> block found; appended progressive skill guidance instead.");
@@ -69,7 +88,7 @@ export function rewritePrompt(systemPrompt: string, skills: Map<string, SkillRec
     } else {
       next = next.replace(skillBlockRegex, replacement);
       changed = true;
-      removedSections.push("available_skills descriptions");
+      removedSections.push(`available_skills descriptions (${config.skillDisplay.mode} display)`);
     }
   }
 

package/.pi/extensions/takomi-context-manager/types.ts

@@ -22,7 +22,14 @@ export type PolicyPack = {
 
 export type Prerequisite = { type: "policies"; policies: string[] };
 
+export type SkillIndexDisplayMode = "hidden" | "candidates" | "all-names" | "auto";
+
 export type ContextManagerConfig = {
+  skillDisplay: {
+    mode: SkillIndexDisplayMode;
+    maxVisibleSkillNames: number;
+    alwaysShowToolInstructions: boolean;
+  };
   candidateRouter: {
     maxCandidates: number;
     highConfidence: number;

package/.pi/extensions/takomi-runtime/index.ts

@@ -1,5 +1,6 @@
 import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { StringEnum } from "@mariozechner/pi-ai";
 import { Type } from "typebox";
@@ -17,8 +18,10 @@ import {
   normalizeSessionState,
   renderMasterPlan,
   renderTaskFile,
+  renderValidationReport,
   serializeSessionState,
   slugifyTaskTitle,
+  validateSessionState,
   type OrchestratorTask,
   type OrchestratorSessionState,
   type OrchestratorTaskStatus,
@@ -57,7 +60,7 @@ import {
   getProfileDefaults,
   loadTakomiProfile,
 } from "./profile";
-import { installTakomiRoutingPolicy, loadTakomiRoutingPolicy } from "./routing-policy";
+import { installTakomiRoutingPolicy, resolveTakomiRoutingPolicy } from "./routing-policy";
 
 type TakomiState = {
   enabled: boolean;
@@ -69,6 +72,7 @@ type TakomiState = {
   workflow?: TakomiWorkflowId;
   activeSessionId?: string;
   subagentsEnabled: boolean;
+  lastFullPromptKey?: string;
 };
 
 const DEFAULT_STATE: TakomiState = {
@@ -121,7 +125,7 @@ function setStageAndWorkflow(state: TakomiState, stage: VibeLifecycleStage, opti
   state.enabled = true;
 }
 
-function rolePrompt(role: TakomiRole): string {
+function fallbackRolePrompt(role: TakomiRole): string {
   switch (role) {
     case "orchestrator":
       return [
@@ -138,7 +142,6 @@ function rolePrompt(role: TakomiRole): string {
       return [
         "You are operating in Takomi design mode.",
         "Translate genesis context into build-ready UX and visual direction.",
-        "Prefer Gemini or a similarly strong design-oriented model if available.",
       ].join("\n");
     case "code":
       return [
@@ -158,6 +161,43 @@ function rolePrompt(role: TakomiRole): string {
   }
 }
 
+function agentFileNameForRole(role: TakomiRole): string | undefined {
+  switch (role) {
+    case "orchestrator": return "orchestrator.md";
+    case "architect": return "architect.md";
+    case "design": return "designer.md";
+    case "code": return "coder.md";
+    case "review": return "reviewer.md";
+    default: return undefined;
+  }
+}
+
+async function loadRolePrompt(cwd: string, role: TakomiRole): Promise<string> {
+  const fileName = agentFileNameForRole(role);
+  if (!fileName) return fallbackRolePrompt(role);
+
+  const candidates = [
+    path.join(cwd, ".pi", "agents", fileName),
+    path.join(installedAssetRoot("agents"), fileName),
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      const raw = await readFile(candidate, "utf8");
+      const cleaned = stripPromptFrontmatter(raw);
+      if (cleaned) {
+        return [
+          fallbackRolePrompt(role),
+          `Canonical Takomi role mirror loaded from ${candidate}:`,
+          cleaned,
+        ].join("\n\n");
+      }
+    } catch {}
+  }
+
+  return fallbackRolePrompt(role);
+}
+
 function planPrompt(): string {
   return [
     "Takomi planning mode is active.",
@@ -166,14 +206,66 @@ function planPrompt(): string {
   ].join("\n");
 }
 
-function getInjectedPlaybook(state: TakomiState): string | undefined {
+function stripPromptFrontmatter(content: string): string {
+  return content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "").trim();
+}
+
+function stripTemplateOnlyRequestPlaceholder(content: string): string {
+  return content
+    .replace(/\n?---\s*\r?\n\s*## Current User Request\s*\r?\n\s*(?:\$@|\$ARGUMENTS)\s*$/i, "")
+    .replace(/\n?## Current User Request\s*\r?\n\s*(?:\$@|\$ARGUMENTS)\s*$/i, "")
+    .trim();
+}
+
+function installedAssetRoot(kind: "agents" | "prompts"): string {
+  return path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    kind,
+  );
+}
+
+async function loadWorkflowPrompt(cwd: string, workflow: TakomiWorkflowId): Promise<string | undefined> {
+  const fileName = workflow === "vibe-genesis"
+    ? "genesis-prompt.md"
+    : workflow === "vibe-design"
+      ? "design-prompt.md"
+      : "build-prompt.md";
+  const candidates = [
+    path.join(cwd, ".pi", "prompts", fileName),
+    path.join(installedAssetRoot("prompts"), fileName),
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      const raw = await readFile(candidate, "utf8");
+      const cleaned = stripTemplateOnlyRequestPlaceholder(stripPromptFrontmatter(raw));
+      if (cleaned) return cleaned;
+    } catch {}
+  }
+
+  return undefined;
+}
+
+async function getInjectedPlaybook(cwd: string, state: TakomiState, includeFullWorkflow: boolean): Promise<string | undefined> {
   if (!state.workflow) return undefined;
   const workflow = getWorkflowDefinition(state.workflow);
+  const prompt = includeFullWorkflow ? await loadWorkflowPrompt(cwd, state.workflow) : undefined;
+
+  if (includeFullWorkflow) {
+    return [
+      `Active Takomi workflow: ${workflow.title} (${workflow.id}).`,
+      prompt ?? workflow.playbook,
+      workflow.nextStage ? `After this stage, recommend ${workflow.nextStage}.` : "",
+    ].filter(Boolean).join("\n\n");
+  }
+
   return [
-    `${workflow.title} is the active Takomi workflow.`,
+    `Active Takomi workflow: ${workflow.title} (${workflow.id}).`,
     workflow.purpose,
     workflow.preferredModelHint ?? "",
-    workflow.playbook,
+    `Compact reminder: follow the ${workflow.id} stage. Full workflow was injected when this role/workflow became active; reload the markdown prompt only if behavior degrades or the task is complex.`,
     workflow.nextStage ? `After this stage, recommend ${workflow.nextStage}.` : "",
   ].filter(Boolean).join("\n\n");
 }
@@ -302,6 +394,37 @@ async function loadSessionState(cwd: string, sessionId: string): Promise<{ state
   return { state, paths };
 }
 
+function repairTaskMarkdown(content: string): string {
+  return content
+    .replace(/### Required Skills/g, "### Optional Skill / Context Overlays")
+    .replace(/Required Skills/g, "Optional Skill / Context Overlays")
+    .replace(/Load ALL required skills/g, "Use relevant optional skill/context overlays only when available and genuinely helpful")
+    .replace(/Required skills/g, "Optional skill/context overlays")
+    .replace(/required skills/g, "optional skill/context overlays");
+}
+
+async function findExistingTaskFile(paths: ReturnType<typeof getSessionPaths>, task: OrchestratorTask): Promise<string | undefined> {
+  for (const folder of [paths.pending, paths.inProgress, paths.completed, paths.blocked]) {
+    const entries = await readdir(folder).catch(() => [] as string[]);
+    const match = entries.find((entry) => entry.endsWith(".task.md") && entry.startsWith(`${task.id}_`));
+    if (match) return path.join(folder, match);
+  }
+  return undefined;
+}
+
+async function writeTaskArtifact(paths: ReturnType<typeof getSessionPaths>, state: OrchestratorSessionState, task: OrchestratorTask) {
+  const targetPath = path.join(getTaskFolder(paths, task.status), getTaskFileName(task));
+  const existingPath = await findExistingTaskFile(paths, task);
+  if (!existingPath) {
+    await writeFile(targetPath, renderTaskFile(task, `Parent session: ${state.sessionId}\n\nTask title: ${task.title}`), "utf8");
+    return;
+  }
+
+  const existing = repairTaskMarkdown(await readFile(existingPath, "utf8"));
+  await writeFile(targetPath, existing, "utf8");
+  if (existingPath !== targetPath) await rm(existingPath, { force: true });
+}
+
 async function syncTaskArtifacts(cwd: string, session: OrchestratorSessionState) {
   const normalizedState = normalizeSessionState(session);
   const paths = getSessionPaths(cwd, normalizedState.sessionId);
@@ -310,7 +433,11 @@ async function syncTaskArtifacts(cwd: string, session: OrchestratorSessionState)
   await mkdir(paths.completed, { recursive: true });
   await mkdir(paths.blocked, { recursive: true });
   await mkdir(paths.stateDir, { recursive: true });
-  await writeFile(paths.masterPlan, renderMasterPlan(normalizedState), "utf8");
+  const existingMasterPlan = await readFile(paths.masterPlan, "utf8").catch(() => "");
+  if (!existingMasterPlan || existingMasterPlan.includes("takomi-generated-master-plan")) {
+    await writeFile(paths.masterPlan, renderMasterPlan(normalizedState), "utf8");
+  }
+  const validation = validateSessionState(normalizedState);
   await writeFile(paths.summary, [
     `# Orchestrator Summary: ${normalizedState.title}`,
     "",
@@ -319,21 +446,16 @@ async function syncTaskArtifacts(cwd: string, session: OrchestratorSessionState)
     `- Machine state: ${paths.stateFile}`,
     `- Runtime mode: ${normalizedState.mode}`,
     `- Session intent: ${normalizedState.sessionIntent ?? "full-project"}`,
+    `- Validation: ${validation.ok ? "PASS" : "ERRORS"} (${validation.errors.length} errors, ${validation.warnings.length} warnings)`,
+    "",
+    "## Validation",
+    "",
+    renderValidationReport(validation),
   ].join("\n"), "utf8");
   await writeFile(paths.stateFile, serializeSessionState(normalizedState), "utf8");
 
-  for (const folder of [paths.pending, paths.inProgress, paths.completed, paths.blocked]) {
-    const entries = await readdir(folder).catch(() => [] as string[]);
-    for (const entry of entries) {
-      if (entry.endsWith(".task.md")) {
-        await rm(path.join(folder, entry), { force: true });
-      }
-    }
-  }
-
   for (const task of normalizedState.tasks) {
-    const filePath = path.join(getTaskFolder(paths, task.status), getTaskFileName(task));
-    await writeFile(filePath, renderTaskFile(task, `Parent session: ${normalizedState.sessionId}\n\nTask title: ${task.title}`), "utf8");
+    await writeTaskArtifact(paths, normalizedState, task);
   }
 
   return paths;
@@ -346,6 +468,7 @@ async function writeOrchestratorSession(cwd: string, session: OrchestratorSessio
 type IncomingTask = {
   id?: string;
   title: string;
+  taskMarkdown?: string;
   role: TakomiRole;
   stage?: VibeLifecycleStage;
   workflow?: TakomiWorkflowId;
@@ -657,9 +780,11 @@ export default function takomiRuntime(pi: ExtensionAPI) {
     name: "takomi_board",
     label: "Takomi Board",
     description: "Create and manage lifecycle-aware Takomi orchestration session artifacts.",
-    promptSnippet: "Create or expand a Genesis -> Design -> Build orchestration session only when the work is large enough to merit it.",
+    promptSnippet: "Track/delegate a Genesis -> Design -> Build orchestration session after the core plan has been authored in markdown.",
     promptGuidelines: [
       "Use this when you need a concrete orchestrator session directory and task artifacts on disk.",
+      "Do not use takomi_board as a substitute for authoring PRD, issue, design, build, master-plan, or task markdown. Write the human-facing markdown first, then use this tool to register/preserve it for state tracking and dispatch.",
+      "For high-quality orchestration sessions, provide masterPlanMarkdown and taskMarkdown values that contain the authored plan/task packets; JSON fields should carry IDs/status/roles/workflow/dependencies/checklists for tracking, not replace expressive markdown.",
       "A new session should normally begin Genesis-first, then expand Design and Build into as many tasks as the scope actually needs.",
       "If the request is small enough, do not force orchestration just because the tool exists.",
       "If a reviewed task needs more work, keep or reuse its conversationId so the same subagent can continue it.",
@@ -692,9 +817,11 @@ export default function takomiRuntime(pi: ExtensionAPI) {
         index: Type.Optional(Type.Number()),
         done: Type.Optional(Type.Boolean()),
       }))),
+      masterPlanMarkdown: Type.Optional(Type.String()),
       tasks: Type.Optional(Type.Array(Type.Object({
         id: Type.Optional(Type.String()),
         title: Type.String(),
+        taskMarkdown: Type.Optional(Type.String()),
         role: StringEnum(["general", "orchestrator", "architect", "design", "code", "review"] as const),
         stage: Type.Optional(StringEnum(["genesis", "design", "build"] as const)),
         workflow: Type.Optional(StringEnum(["vibe-genesis", "vibe-design", "vibe-build"] as const)),
@@ -1059,6 +1186,15 @@ ${stateJson}` }],
         );
         nextState = markStageExpanded(nextState, params.stage, params.notes);
         const paths = await writeOrchestratorSession(ctx.cwd, nextState);
+        if (params.masterPlanMarkdown?.trim()) {
+          await writeFile(paths.masterPlan, params.masterPlanMarkdown.trimEnd() + "\n", "utf8");
+        }
+        for (const task of nextState.tasks) {
+          const authored = (params.tasks as IncomingTask[] | undefined)?.find((input) => (input.id ?? task.id) === task.id)?.taskMarkdown;
+          if (authored?.trim()) {
+            await writeFile(path.join(getTaskFolder(paths, task.status), getTaskFileName(task)), authored.trimEnd() + "\n", "utf8");
+          }
+        }
         state.activeSessionId = nextState.sessionId;
         persistState();
         syncContextPanelState();
@@ -1088,6 +1224,15 @@ ${stateJson}` }],
         },
       );
       const paths = await writeOrchestratorSession(ctx.cwd, nextState);
+      if (params.masterPlanMarkdown?.trim()) {
+        await writeFile(paths.masterPlan, params.masterPlanMarkdown.trimEnd() + "\n", "utf8");
+      }
+      for (const task of nextState.tasks) {
+        const authored = (params.tasks as IncomingTask[] | undefined)?.find((input) => (input.id ?? task.id) === task.id)?.taskMarkdown;
+        if (authored?.trim()) {
+          await writeFile(path.join(getTaskFolder(paths, task.status), getTaskFileName(task)), authored.trimEnd() + "\n", "utf8");
+        }
+      }
       state.activeSessionId = nextState.sessionId;
       state.role = "orchestrator";
       state.stage = nextState.lifecycle.genesis.status === "completed" ? "build" : "genesis";
@@ -1181,7 +1326,15 @@ ${stateJson}` }],
       routingNote = "Blank project detected; orchestrator remains in control and must honor Genesis → Design → Build.";
     }
 
-    const routingPolicy = await loadTakomiRoutingPolicy(runtimeCwd);
+    const promptKey = `${effectiveState.role}:${effectiveState.workflow ?? "none"}`;
+    const includeFullWorkflow = Boolean(effectiveState.workflow && effectiveState.lastFullPromptKey !== promptKey);
+    if (includeFullWorkflow) {
+      state.lastFullPromptKey = promptKey;
+      persistState();
+      syncContextPanelState();
+    }
+
+    const routingPolicy = await resolveTakomiRoutingPolicy(runtimeCwd);
     const modelPreflightContext = (() => {
       try {
         const available = typeof (runtimeCtx as { modelRegistry?: { getAvailable?: () => Array<{ provider?: string; id?: string; name?: string }> } } | undefined)?.modelRegistry?.getAvailable === "function"
@@ -1196,11 +1349,13 @@ ${stateJson}` }],
 
     const parts = [
       "Takomi runtime is active for this turn.",
-      rolePrompt(effectiveState.role),
+      await loadRolePrompt(runtimeCwd, effectiveState.role),
       effectiveState.planMode ? planPrompt() : "",
-      getInjectedPlaybook(effectiveState),
+      await getInjectedPlaybook(runtimeCwd, effectiveState, includeFullWorkflow),
       `Routing note: ${routingNote}`,
-      routingPolicy ? `Project Takomi model routing policy is active. Apply it when choosing parent/subagent models and escalation levels:\n\n${routingPolicy}` : "No project Takomi model routing policy file was found. Users can install one with `/takomi routing <policy>` or by saying `Update Takomi routing logic: \"\"\"...\"\"\"`.",
+      routingPolicy.text
+        ? `${routingPolicy.source === "bundled" ? "Bundled" : "Project"} Takomi model routing policy is active. Apply it when choosing parent/subagent models and escalation levels:\n\n${routingPolicy.text}`
+        : "No Takomi routing policy file was found. Users can install one with `/takomi routing <policy>` or by saying `Update Takomi routing logic: \"\"\"...\"\"\"`.",
       modelPreflightContext,
       `Execution mode: ${route.executionMode}. Session recommendation: ${route.sessionRecommendation}.`,
       `Takomi execution gate: ${effectiveState.launchMode === "manual" ? "review" : "auto"}. In review gate mode, show the delegation plan before launching and return to the user after each task with results, verification guidance, and the recommended next step.`,