takomi 2.1.35 → 2.1.37

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

@@ -81,9 +81,9 @@ export function renderRuntimeStatus(theme: Theme, state: RuntimeHudState): strin
   const sourceLabel = source === "manual" ? theme.fg("warning", "manual") : theme.fg("success", source);
   const role = state.stage && state.role !== state.stage ? theme.fg("dim", state.role) : "";
   const plan = state.planMode ? theme.fg("warning", "plan") : theme.fg("dim", "direct");
-  const gate = state.launchMode === "manual" ? theme.fg("warning", "review-gate") : "";
+  const gate = state.launchMode === "manual" ? theme.fg("warning", "review-gate") : theme.fg("success", "auto-gate");
   const subagents = state.subagentsEnabled === false ? theme.fg("error", "subagents:off") : "";
-  return [theme.fg("accent", "Takomi"), sourceLabel, stageBadge, role, gate || plan, subagents].filter(Boolean).join(" ");
+  return [theme.fg("accent", "Takomi"), sourceLabel, stageBadge, role, gate, plan, subagents].filter(Boolean).join(" ");
 }
 
 export function renderRuntimeWidget(theme: Theme, state: RuntimeHudState): string[] {
@@ -95,7 +95,7 @@ export function renderRuntimeWidget(theme: Theme, state: RuntimeHudState): strin
     sourceLabel,
     badge(theme, primary, stageTone(state.stage)),
     state.stage && state.role !== state.stage ? theme.fg("dim", `role:${state.role}`) : "",
-    state.launchMode === "manual" ? theme.fg("warning", "review-gate") : "",
+    state.launchMode === "manual" ? theme.fg("warning", "review-gate") : theme.fg("success", "auto-gate"),
     state.planMode ? theme.fg("warning", "plan") : theme.fg("dim", "direct"),
     state.subagentsEnabled === false ? theme.fg("error", "subagents:off") : theme.fg("dim", "subagents:on"),
     state.workflow ? theme.fg("dim", `wf:${state.workflow}`) : "",

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

@@ -1,6 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { renderTakomiSubagentCall, renderTakomiSubagentResult } from "./native-render";
+import { loadPiSubagentsInternals } from "./pi-subagents-internal";
 import { executeTakomiSubagentTool } from "./tool-runner";
 
 const ChecklistItemSchema = Type.Object({
@@ -30,8 +31,24 @@ const TaskSchema = Type.Object({
   checklist: Type.Optional(Type.Array(Type.Union([Type.String(), ChecklistItemSchema]))),
 });
 
+const ContextSchema = Type.Union([
+  Type.Literal("fresh"),
+  Type.Literal("fork"),
+]);
+
+const ActionSchema = Type.Union([
+  Type.Literal("list"),
+  Type.Literal("get"),
+  Type.Literal("models"),
+  Type.Literal("status"),
+  Type.Literal("interrupt"),
+  Type.Literal("resume"),
+  Type.Literal("doctor"),
+]);
+
 const SubagentParameters = Type.Object({
-  agent: Type.Optional(Type.String({ description: "Agent name for single execution" })),
+  action: Type.Optional(ActionSchema),
+  agent: Type.Optional(Type.String({ description: "Agent name for single execution, or target agent for get/models actions" })),
   task: Type.Optional(Type.String({ description: "Task for single execution" })),
   workflow: Type.Optional(Type.String({ description: "Workflow or playbook overlay for this task" })),
   skills: Type.Optional(Type.Array(Type.String(), { description: "Extra skills to apply during the task" })),
@@ -46,6 +63,14 @@ const SubagentParameters = Type.Object({
   previewOnly: Type.Optional(Type.Boolean({ description: "Return the delegation plan without launching" })),
   clarify: Type.Optional(Type.Boolean({ description: "Show the native pi-subagents TUI to preview/edit before execution. Especially useful for chains; requires an interactive Pi TUI." })),
   chain: Type.Optional(Type.Array(TaskSchema, { description: "Sequential chain of subagent tasks" })),
+  context: Type.Optional(ContextSchema),
+  async: Type.Optional(Type.Boolean({ description: "Run through native pi-subagents background/async mode" })),
+  concurrency: Type.Optional(Type.Number({ description: "Maximum concurrency for parallel task groups" })),
+  worktree: Type.Optional(Type.Boolean({ description: "Use native pi-subagents worktree isolation where supported" })),
+  id: Type.Optional(Type.String({ description: "Native async/control run id for status, interrupt, or resume actions" })),
+  message: Type.Optional(Type.String({ description: "Follow-up message for resume actions" })),
+  index: Type.Optional(Type.Number({ description: "Child index for resume actions when needed" })),
+  chainName: Type.Optional(Type.String({ description: "Saved chain name for get actions" })),
   agentScope: Type.Optional(Type.Union([Type.Literal("user"), Type.Literal("project"), Type.Literal("both")])),
   // Project-agent confirmation and hard-stop overrides are enforced server-side;
   // they are intentionally not model-callable parameters.
@@ -55,11 +80,14 @@ function registerSubagentTool(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "takomi_subagent",
     label: "Takomi",
-    description: "Run subagents with Pi-style single, parallel, or chain modes plus Takomi lifecycle metadata.",
-    promptSnippet: "Delegate lifecycle-aware Takomi work to specialist subagents. Use single, tasks, or chain; reuse conversationId for review loops.",
+    description: "Run subagents with Pi-style single, parallel, chain, async, fork, and management/status modes plus Takomi lifecycle metadata.",
+    promptSnippet: "Delegate lifecycle-aware Takomi work to specialist subagents. Use single, tasks, chain, or action=list/status/doctor; reuse conversationId for review loops.",
     promptGuidelines: [
       "Use this tool during orchestration when a specialist should handle a task.",
+      "Use action=list to discover agents and action=status/doctor for native pi-subagents diagnostics/control instead of raw subagent.",
       "Use tasks for independent parallel work and chain for dependent handoffs with {previous}.",
+      "Set context=fork only when inherited parent-session history is needed; otherwise prefer fresh or the agent default.",
+      "Set async=true for long-running work when the parent can continue safely; keep active worktree writes single-threaded unless worktree isolation is enabled.",
       "Set clarify=true when the user asks to preview/edit a subagent run in the native Pi TUI before launch.",
       "Use model, fallbackModels, and thinking only when deliberate; otherwise let the agent/profile defaults apply.",
       "If review sends work back to the same agent, reuse the same conversationId for continuity.",
@@ -74,6 +102,11 @@ function registerSubagentTool(pi: ExtensionAPI): void {
   });
 }
 
-export default function takomiSubagents(pi: ExtensionAPI) {
+export default async function takomiSubagents(pi: ExtensionAPI) {
+  // Preload the native pi-subagents renderer before tool registration. Rendering
+  // callbacks are synchronous, so if we only lazy-load internals during execution
+  // a completed takomi_subagent result can fall back to Takomi's plain text
+  // renderer and lose the native compact/expanded details shown by `subagent`.
+  await loadPiSubagentsInternals();
   registerSubagentTool(pi);
 }

package/.pi/extensions/takomi-subagents/native-render.ts

@@ -38,12 +38,16 @@ function resultText(result: ToolResult): string {
       : JSON.stringify((result as any)?.details ?? {}, null, 2);
 }
 
-function summarizeCollapsedResult(text: string, status: string, theme: Theme): string {
+function extractPolicyNames(text: string): string[] {
   const policyMatch = text.match(/Required policies:\n((?:- .+\n?)+)/);
-  const policies = policyMatch?.[1]
+  return policyMatch?.[1]
     ?.split("\n")
     .map((line) => line.replace(/^[-\s]+/, "").trim())
     .filter(Boolean) ?? [];
+}
+
+function summarizeCollapsedResult(text: string, status: string, theme: Theme): string {
+  const policies = extractPolicyNames(text);
   const lineCount = text ? text.split(/\r?\n/).length : 0;
   const label = policies.length > 0
     ? `policy context loaded: ${policies.join(", ")}`
@@ -53,22 +57,89 @@ function summarizeCollapsedResult(text: string, status: string, theme: Theme): s
   return `${theme.fg(color, `${icon} takomi_subagent ${status}`)}${theme.fg("dim", ` · ${label} (ctrl+o to expand)`)}`;
 }
 
+function isPolicyGateBlock(text: string): boolean {
+  return /^Blocked\s+takomi_subagent:\s+required policy context had not been loaded yet\./m.test(text)
+    && /\nRequired policies:\n/.test(text)
+    && /\nLoaded policy context:\n/.test(text);
+}
+
+function renderPolicyGateBlock(text: string, expanded: boolean | undefined, theme: Theme): string {
+  const policies = extractPolicyNames(text);
+  const lineCount = text ? text.split(/\r?\n/).length : 0;
+  const policyLabel = policies.length ? policies.join(", ") : "required policy";
+  if (!expanded) {
+    return [
+      theme.fg("warning", "⚠ takomi_subagent blocked"),
+      theme.fg("dim", `Required policy context loaded for this session: ${policyLabel}.`),
+      theme.fg("dim", `Retry the original tool call. ${lineCount} policy lines hidden (ctrl+o to expand).`),
+    ].join("\n");
+  }
+  return [
+    theme.fg("warning", "⚠ takomi_subagent blocked"),
+    theme.fg("dim", "Policy context was loaded and passed back to the model; retry the original call."),
+    theme.fg("dim", "Press ctrl+o again to collapse."),
+    "",
+    text,
+  ].join("\n");
+}
+
 function recentOutputLines(value: unknown): string[] {
   if (Array.isArray(value)) return value.map(String).filter(Boolean).slice(-3);
   if (typeof value === "string") return value.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).slice(-3);
   return [];
 }
 
+function normalizeLiveStatus(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  if (value === "complete") return "completed";
+  if (value === "in-progress") return "running";
+  if (value === "timed-out") return "failed";
+  return value;
+}
+
+function rawLiveStatus(row: any): string {
+  const explicit = normalizeLiveStatus(
+    typeof row?.progress?.status === "string" ? row.progress.status
+      : typeof row?.status === "string" ? row.status
+        : undefined,
+  );
+  if (explicit) return explicit;
+
+  const exitCode = typeof row?.exitCode === "number" ? row.exitCode
+    : typeof row?.code === "number" ? row.code
+      : undefined;
+  if (exitCode === 0) return "completed";
+  if (exitCode === undefined || exitCode === null || exitCode === -1) return "running";
+  return "failed";
+}
+
+function isLiveTerminalStatus(status: string): boolean {
+  return ["completed", "failed", "blocked", "detached", "paused"].includes(status);
+}
+
+function displayLiveStatus(status: string, allRowsTerminal: boolean): string {
+  // Native pi-subagents can emit one last partial update after the child process
+  // reaches exitCode 0 but before the takomi_subagent tool result has actually
+  // settled. In that window the tool card is still partial/running, so showing a
+  // child as "completed" is misleading. Call it finalizing until Pi renders the
+  // real final result.
+  if (allRowsTerminal && status === "completed") return "finalizing";
+  return status;
+}
+
 function livePartialText(result: ToolResult, theme: Theme): string {
   const details = (result as any)?.details ?? {};
   const results = Array.isArray(details.results) ? details.results : [];
   const progress = Array.isArray(details.progress) ? details.progress : [];
+  const rows = results.length ? results : progress;
+  const rawStatuses = rows.map(rawLiveStatus);
+  const allRowsTerminal = rows.length > 0 && rawStatuses.every(isLiveTerminalStatus);
+  const titleStatus = allRowsTerminal ? "finalizing" : "running";
   const lines = [
-    theme.fg("toolTitle", theme.bold("takomi_subagent running")),
+    theme.fg("toolTitle", theme.bold(`takomi_subagent ${titleStatus}`)),
     theme.fg("dim", "Live detail is bounded while streaming so manual scroll/ctrl+o does not jump on every token."),
   ];
 
-  const rows = results.length ? results : progress;
   if (!rows.length) {
     const text = resultText(result).split(/\r?\n/).find((line) => line.trim())?.trim();
     lines.push(theme.fg("dim", text || "Waiting for subagent progress…"));
@@ -76,7 +147,7 @@ function livePartialText(result: ToolResult, theme: Theme): string {
   }
 
   rows.slice(0, 6).forEach((row: any, index: number) => {
-    const status = row.status ?? (row.exitCode === 0 ? "completed" : row.exitCode === -1 ? "running" : row.exitCode === undefined ? "running" : "failed");
+    const status = displayLiveStatus(rawStatuses[index] ?? rawLiveStatus(row), allRowsTerminal);
     const agent = row.agent ?? `task ${index + 1}`;
     const task = String(row.task ?? "").replace(/\s+/g, " ").trim();
     const currentTool = row.currentTool ?? row.progress?.currentTool;
@@ -93,15 +164,21 @@ function livePartialText(result: ToolResult, theme: Theme): string {
 }
 
 export function renderTakomiSubagentResult(result: ToolResult, options: { expanded?: boolean; isPartial?: boolean }, theme: Theme, context: any): any {
-  const status = (result as any)?.isError ? "failed" : options.isPartial ? "running" : "completed";
+  const status = ((result as any)?.isError || context?.isError) ? "failed" : options.isPartial ? "running" : "completed";
   const text = resultText(result);
 
+  if (isPolicyGateBlock(text)) {
+    return new Text(renderPolicyGateBlock(text, options.expanded, theme), 0, 0);
+  }
+
+  const native = renderNativeSubagentResult(result, options, theme, context);
+  if (options.isPartial && native) return native;
+
   if (options.isPartial) {
     if (options.expanded) return new Text(livePartialText(result, theme), 0, 0);
     return new Text(summarizeCollapsedResult(text, status, theme), 0, 0);
   }
 
-  const native = renderNativeSubagentResult(result, options, theme, context);
   if (native) return native;
 
   if (!options.expanded) {

package/.pi/extensions/takomi-subagents/pi-subagents-engine.ts

@@ -54,7 +54,8 @@ function createState(): SubagentState {
   };
 }
 
-function resolveMode(params: TakomiSubagentToolParams): "single" | "parallel" | "chain" | undefined {
+function resolveMode(params: TakomiSubagentToolParams): "single" | "parallel" | "chain" | "action" | undefined {
+  if (params.action) return "action";
   const hasChain = Boolean(params.chain?.length);
   const hasParallel = Boolean(params.tasks?.length);
   const hasSingle = Boolean(params.agent && params.task);
@@ -205,13 +206,27 @@ function toSubagentParams(params: TakomiSubagentToolParams, rootCwd: string, dis
   const base = {
     agentScope: params.agentScope ?? "both",
     cwd: rootCwd,
-    context: "fresh" as const,
-    async: false,
+    ...(params.context ? { context: params.context } : {}),
+    ...(params.async !== undefined ? { async: params.async } : {}),
+    ...(params.concurrency !== undefined ? { concurrency: params.concurrency } : {}),
+    ...(params.worktree !== undefined ? { worktree: params.worktree } : {}),
     clarify: params.clarify === true,
     includeProgress: true,
     sessionDir: stableConversationSessionDir(rootCwd, tasks),
   };
 
+  if (mode === "action") {
+    return {
+      ...base,
+      action: params.action,
+      agent: params.agent,
+      chainName: params.chainName,
+      id: params.id,
+      message: params.message,
+      index: params.index,
+    };
+  }
+
   if (mode === "single") {
     const task = tasks[0]!;
     const mapped = mapSingleTask(task, names, rootCwd);

package/.pi/extensions/takomi-subagents/tool-runner.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { TakomiThinkingLevel } from "../../../src/pi-takomi-core";
+import type { TakomiLaunchMode, TakomiThinkingLevel } from "../../../src/pi-takomi-core";
 import { loadTakomiProfile } from "../takomi-runtime/profile";
 import { applyTakomiRoutingDefaults, loadTakomiModelRoutingSnapshot } from "../takomi-runtime/model-routing-defaults";
 import { resolveAgentName } from "./agent-aliases";
@@ -25,11 +25,20 @@ export type TakomiSubagentToolTask = {
 };
 
 export type TakomiSubagentToolParams = Partial<TakomiSubagentToolTask> & {
+  action?: "list" | "get" | "models" | "status" | "interrupt" | "resume" | "doctor";
   tasks?: TakomiSubagentToolTask[];
   chain?: TakomiSubagentToolTask[];
   confirmLaunch?: boolean;
   previewOnly?: boolean;
   clarify?: boolean;
+  context?: "fresh" | "fork";
+  async?: boolean;
+  concurrency?: number;
+  worktree?: boolean;
+  id?: string;
+  message?: string;
+  index?: number;
+  chainName?: string;
   agentScope?: TakomiAgentScope;
 };
 
@@ -192,6 +201,17 @@ function withNativeHardStop(result: any, hardStop: { reason: string; message: st
     },
   };
 }
+
+function readRuntimeLaunchMode(ctx: ExtensionContext): TakomiLaunchMode | undefined {
+  const entries = ctx.sessionManager.getEntries();
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const entry = entries[i] as { type?: string; customType?: string; data?: { launchMode?: unknown } };
+    if (entry.type !== "custom" || entry.customType !== "takomi-runtime-state") continue;
+    if (entry.data?.launchMode === "manual" || entry.data?.launchMode === "auto") return entry.data.launchMode;
+  }
+  return undefined;
+}
+
 function resolveMode(params: TakomiSubagentToolParams): "single" | "parallel" | "chain" | undefined {
   const hasChain = Boolean(params.chain?.length);
   const hasParallel = Boolean(params.tasks?.length);
@@ -234,7 +254,34 @@ export async function executeTakomiSubagentTool(
     return textResult(message, { results: [], agentScope: params.agentScope ?? "both" }, true);
   }
   const profile = await loadTakomiProfile(rootCwd);
+  const runtimeLaunchMode = readRuntimeLaunchMode(ctx);
   const agentScope = params.agentScope ?? "both";
+
+  if (params.action) {
+    try {
+      const nativeResult: any = await engine.execute(
+        "takomi-tool",
+        { ...params, cwd: rootCwd, agentScope },
+        signal,
+        onUpdate as any,
+        ctx,
+      );
+      return {
+        ...nativeResult,
+        details: {
+          ...(nativeResult?.details ?? {}),
+          takomi: {
+            action: params.action,
+            agentScope,
+          },
+        },
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return textResult(message, { results: [], action: params.action, agentScope }, true);
+    }
+  }
+
   const agents = discoverTakomiAgents(rootCwd, agentScope);
   const byName = new Map<string, TakomiAgentConfig>(agents.map((agent) => [agent.name, agent]));
   const mode = resolveMode(params);
@@ -290,7 +337,7 @@ export async function executeTakomiSubagentTool(
   }
   const plan = createTakomiDelegationPlan({
     source: "takomi-tool",
-    launchMode: profile.launchMode ?? "auto",
+    launchMode: runtimeLaunchMode ?? profile.launchMode ?? "auto",
     profile,
     tasks: tasks.map((task, index) => ({
       id: task.conversationId ?? `direct-${index + 1}`,
@@ -316,10 +363,10 @@ export async function executeTakomiSubagentTool(
   }
   try {
     const nativeParams: TakomiSubagentToolParams = mode === "single"
-      ? { ...params, ...tasks[0]!, agentScope }
+      ? { ...params, ...tasks[0]!, cwd: rootCwd, agentScope }
       : mode === "parallel"
-        ? { ...params, tasks, agentScope }
-        : { ...params, chain: tasks, agentScope };
+        ? { ...params, cwd: rootCwd, tasks, agentScope }
+        : { ...params, cwd: rootCwd, chain: tasks, agentScope };
 
     const nativeResult: any = await engine.execute(
       "takomi-tool",

package/README.md

@@ -50,6 +50,8 @@ Legacy commands like `takomi install pi`, `takomi sync pi`, `takomi upgrade`, an
 
 During `takomi setup pi` or `takomi setup pi-features`, Takomi offers optional Pi feature packs with recommended/manual/select-all/skip choices. Current defaults install **Takomi Interview** (`npm:@juicesharp/rpiv-ask-user-question`) so models can ask structured clarification questions. **Takomi Todo** (`npm:@juicesharp/rpiv-todo`), **Takomi Browser QA** (`npm:pi-chrome`), and **Takomi Doc Preview** (`npm:pi-markdown-preview`) remain opt-in. `takomi refresh` runs Pi's package updater so installed optional, custom, old, and new Pi packages are reconciled together.
 
+Takomi keeps `pi-subagents` installed as an internal runtime module, but setup/refresh now detects legacy raw Pi subagent activation (`npm:pi-subagents` in Pi settings or `~/.pi/agent/extensions/subagent`) and offers to disable it so models see `takomi_subagent` instead of two competing subagent tools.
+
 ### Context Manager
 
 Takomi now ships a Pi-native `takomi-context-manager` extension. It reduces prompt bloat with progressive context loading:
@@ -60,10 +62,11 @@ Takomi now ships a Pi-native `takomi-context-manager` extension. It reduces prom
 - `takomi_subagent` is guarded by routing-policy context and can recover from wrong-provider model choices
 - `/context-report` shows prompt compaction, loaded skills/policies, blocked actions, model-routing corrections, and duplicate extension diagnostics
 
+`context_report` is context-manager-specific rather than a clone of Pi's Alt-C window. It restores its own hidden snapshots and Pi tool-result history after `/reload`/restart, and labels any remaining gaps instead of reporting fresh in-memory zeros as session truth. It supports `mode: "summary" | "verbose" | "problems"`; `verbose: true` remains a compatibility alias for `mode: "verbose"`. The `/context-report` slash command supports argument completions for `summary`, `verbose`, and `problems`.
 
 ### Option A: Global Install (Best for Multi-IDE Users) ⭐
 
-Install once. Use everywhere. Your skills follow you across every AI harness(Antigravity, KiloCode, Windsurf, Cursor, Gemini CLI):
+Install once. Use everywhere. Your skills follow you across detected AI harnesses (Antigravity, Claude Code, Codex, Cursor, Kilo Code, Pi/shared Agent Skills, Windsurf):
 
 ```bash
 # Using pnpm
@@ -184,17 +187,21 @@ npx -y skills add https://github.com/JStaRFilms/VibeCode-Protocol-Suite --skill
 
 **One install. Every IDE. Zero friction.**
 
-Takomi v2.0 introduces the **Global Skills Router** — install skills once, and they appear in every AI harness you use. No symlinks. No admin privileges. Works on Mac & Windows.
+Takomi v2.0 introduces the **Global Skills Router** — install skills once into `~/.takomi/`, and Takomi syncs them into each harness' current global skills directory. You can choose symlink/junction mode for one canonical copy, auto fallback, or plain copy mode. Works on Mac & Windows.
+
+Note: `SKILL.md` is portable, but `~/.agents/skills` is **not** a universal global skills directory. Pi does load `~/.agents/skills`, and Takomi keeps that as the Pi/shared Agent Skills target. Other harnesses use their own global paths. See `docs/skills-harness-targets.md` for the current checked path table.
 
 ### Supported Harnesses
 
 | Harness | Global Skills Path | Global Workflows Path |
 |---|---|---|
-| **Antigravity** | `~/.gemini/antigravity/skills/` | `~/.gemini/antigravity/global_workflows/` |
-| **KiloCode** | `~/.kilocode/skills/` | `~/.kilocode/workflows/` |
+| **Antigravity** | `~/.gemini/config/skills/` | `~/.gemini/config/global_workflows/` |
+| **Claude Code** | `~/.claude/skills/` | _(skills only)_ |
+| **Codex** | `~/.codex/skills/` | _(skills only)_ |
+| **Cursor** | `~/.cursor/skills/` | _(skills only)_ |
+| **Kilo Code** | `~/.kilocode/skills/` | `~/.kilocode/workflows/` |
+| **Pi / shared Agent Skills** | `~/.agents/skills/` | _(skills only)_ |
 | **Windsurf** | `~/.codeium/windsurf/skills/` | `~/.codeium/windsurf/global_workflows/` |
-| **Global agents-compatible CLIs** _(e.g., Codex, Gemini CLI)_ | `~/.agents/skills/` | _(skills only)_ |
-| **Cursor** | `~/.cursor/skills/` | _(uses rules)_ |
 
 ### CLI Commands
 
@@ -505,7 +512,7 @@ Externally sourced skills and optional Pi packages retain credit to their upstre
 - **Context7**: From [upstash/context7](https://github.com/upstash/context7) — fresh library documentation fetcher.
 - **Audit Website**: From [squirrelscan/skills](https://github.com/squirrelscan/skills) — professional website auditor.
 - **Convex Skills**: From [waynesutton/convexskills](https://github.com/waynesutton/convexskills) — complete Convex development suite including **Functions**, **Schema Validation**, **Realtime**, **Agents**, **File Storage**, **Migrations**, **HTTP Actions**, **Cron Jobs**, **Component Authoring**, **Best Practices**, **Security Audit**, **Security Check**, **Avoid Feature Creep**, and **Optimize Agent Context**.
-- **Gemini CLI**: Custom VibeCode skill for large-context processing with Gemini 3 Pro.
+- **Anti-Gravity**: Custom skill for running Google's current Anti-Gravity CLI workflow for large-context review and analysis.
 - **Google Stitch Skills**: From [google-labs-code/stitch-skills](https://github.com/google-labs-code/stitch-skills) — Design-to-code suite including **design-md**, **enhance-prompt**, **stitch-loop**, **react-components**, and **shadcn-ui**.
 - **Jules**: From [sanjay3290/ai-skills](https://github.com/sanjay3290/ai-skills) — delegate coding tasks to Google Jules AI agent.
 - **Subagent Execution**: Built on **[`pi-subagents`](https://github.com/nicobailon/pi-subagents)** by **Nico Bailon** — providing the underlying Pi extension for delegated subagent runs (result rendering, live progress, single/parallel/chain execution, session/artifact handling, and related subagent tooling), upon which Takomi adds its own lifecycle orchestration, model-routing policy, and workflow metadata.

package/assets/.agent/skills/exam-creator-skill/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: exam-creator-skill
+description: Creates and revises school exam papers using Johno's preferred workflow. Use for JSS/Primary exam generation, remixing questions from lesson notes or chat transcripts, building question papers plus marking schemes, creating assets folders for diagrams, applying the 40-mark house style, producing compact DOCX output, and running draft/marking/verification passes with room for user feedback and revisions.
+---
+
+# Exam Creator Skill
+
+Use this skill when building or revising school exam papers, especially for OBHIS / Olive Blessed Crest Academy.
+
+See the detailed house rules in [references/workflow-rulebook.md](references/workflow-rulebook.md).
+See the model routing policy in [references/model-routing-policy.md](references/model-routing-policy.md).
+
+## Core Principle
+
+Follow the user's house style by default, but always leave room for correction. If the user gives a new rule, prefer the new rule and update the working assumptions before generating more papers.
+
+Terminology rule: when the user says **Gemini**, treat that as **Gemini via the agy CLI** unless the user explicitly says otherwise.
+
+## Default Workflow
+
+1. **Identify the subject, class, term, and destination folder.**
+2. **Collect the authority material**:
+   - lesson notes
+   - ChatGPT transcripts
+   - sample exam layout if provided
+   - photographed handwritten pages, when provided
+3. **For photographed handwritten pages, extract with multimodal vision first**:
+   - use a multimodal model/subagent to read the image directly
+   - batch images in small ordered groups, usually 3-5 images per extraction task
+   - explicitly forbid OCR/Tesseract/Python preprocessing on the first pass unless the model is not multimodal
+   - use OCR only as fallback when direct model vision is unavailable or fails on a specific page
+   - preserve image filename/page references for every uncertain item
+4. **Confirm the paper pattern before drafting** if any of these are unclear:
+   - subject family (Mathematics/English vs other subjects)
+   - mark split
+   - question counts
+   - whether theory is answer-all or answer-any
+5. **Create or reuse clean folders**:
+   - `Questions/`
+   - `Marking Scheme/` only when requested
+   - `Questions/assets/` for all generated SVG/PNG/image diagrams
+6. **Draft the paper first.**
+7. **Create the marking scheme second only when requested.**
+8. **Run an independent verification pass third.**
+9. **Apply user feedback and rerender** instead of defending the first draft.
+
+## Preferred Multi-Agent Pattern
+
+Default model split:
+- orchestrator: parent assistant
+- drafting: Gemini via agy CLI by default, escalate to GPT 5.4 High when the paper is tricky
+- marking: Gemini via agy CLI
+- verification: GPT
+
+When subagents are available, use this split:
+
+- **Drafting agent**: creates the paper and diagram assets.
+- **Marking agent**: creates the marking scheme and validates every objective answer.
+- **Review agent**: independently rechecks answers, numbering, marks, wording, and diagram correctness.
+
+If subagents are not available, still preserve the same three-pass logic manually.
+
+## House Rules To Hardcode
+
+### 1) Marks and paper shape
+
+#### Mathematics and English
+Use this as the default unless the user overrides it:
+
+- total exam score: **40 marks**
+- **50 objective questions**
+- each objective = **1/2 mark**
+- objective total = **25 marks**
+- **5 theory questions**
+- student answers **any 3**
+- theory total = **15 marks**
+- no separate Section B short-answer block unless the user explicitly asks for one
+
+#### Other subjects
+Default assumption:
+
+- still over **40 marks** total
+- can include open-ended plus theory sections
+- if the exact split is not stated, ask before finalizing
+
+Never silently reuse the old 100-mark structure unless the user explicitly asks for it.
+
+### 2) Layout rules
+
+For the final paper DOCX, prefer:
+
+- **Times New Roman**
+- use one font size consistently within a paper; **start with 14 pt** and only reduce it if layout pressure makes it necessary
+- narrow margins
+- every exam header should include, in this order where possible: school name, academic session, term/exam title, pupil name/date line, examination number/time line, class, arm, subject, and instructions
+- header must be **1-column**
+- body should be **1-column by default**; use 2-column or 3-column only when it genuinely improves fit for dense objective papers
+- do not apply a multi-column body just because the skill mentions compact layout; use judgment per subject
+- bold black headings instead of oversized decorative headings
+- objective options must start on the **same line as the question** whenever possible; keep them inline with about 3 spaces between choices, not vertically stacked unless unavoidable
+- if the paper looks like it will run to **3 pages**, try a **2-column or 3-column body layout** before reducing the font size; use judgment based on content density
+- preserve the school name and student-detail heading fields from the source, or leave clear blanks/placeholders if they are not provided
+- if the source uses an arm/stream/class line, keep it but do not hardcode labels like `Arm:` unless the source explicitly requires them
+- when using separate header/body sections in DOCX, make the body section **continuous** so it does not jump to a new page
+- avoid hard page breaks between the heading block and the paper body unless the user explicitly asks for a new page
+- remove explicit `Total Marks: ...` header line unless requested
+- target about **2 pages** per paper where practical
+
+### 3) Diagram and image rules
+
+- Keep all generated figures inside `Questions/assets/`.
+- Choose the diagram method by complexity:
+  - simple geometric/line diagrams, tables, clocks, arrows, and labels: SVG first; generate PNG copies if DOCX rendering needs them
+  - pictorial objects for young pupils, e.g. mango, pot, bucket, moon, table, cup, house, animals, people, classroom objects: prefer Anti-Gravity image generation or another image-generation path, then place the generated PNG/JPG in `Questions/assets/`
+  - hybrid diagrams: combine clean SVG labels/structure with generated image assets when useful
+- When using Anti-Gravity for diagrams, explicitly tell it whether to generate images, use SVG, or use a hybrid method, and require it to report which method was used.
+- Never include the teacher's written answer labels in student-facing diagrams. If the source labels a keyboard as "Keyboard" or groups division answers for marking guidance, remove that answer/label from the final exam.
+- Keep diagrams separated when the source has separate question items or separate objects that must be arranged on the paper. Do not combine unrelated drawings into one asset just for convenience; combine only when the source/question explicitly presents them as one group.
+- Preserve the source question order for diagram-heavy nursery/primary papers by rebuilding from the original images, not only from extraction summaries.
+- If an item asks pupils to colour an object or flag, do not colour it in the exam; provide an outline only unless the instruction asks for a sample.
+- Keep angle labels and vertex labels clearly visible for geometry.
+- Avoid placing numbers directly on triangle edges.
+- If labels are cramped, move them outward and add white-backed label boxes if needed.
+
+### 4) Feedback loop
+
+After each significant draft:
+
+- expect user corrections
+- revise quickly
+- update the source files and rerender the DOCX
+- if the DOCX is locked/open, save a `v2` file rather than failing the task
+
+## Output Expectations
+
+For each subject batch, try to maintain:
+
+- editable paper source, usually `questions.md`
+- concise support/source metadata if useful
+- final DOCX for the paper
+- marking scheme source
+- final DOCX for the marking scheme when requested
+- objective-validation notes
+- verification report
+- all diagrams in `Questions/assets/`
+
+## Authoring Guidance
+
+- Keep questions standard and school-appropriate.
+- Remix questions reasonably from the provided curriculum material.
+- Stay within the authority source unless the user allows expansion.
+- Make objective questions unambiguous.
+- Do not leak answers from teacher notes, source annotations, labels, grouped examples, or marking cues into the student-facing paper.
+- For handwritten sources, try hard to infer unclear words from context, subject vocabulary, options, and neighboring pages before marking `[unclear]`.
+- If uncertainty remains, create a user-review list with image filename/page number, question number, cropped/quoted context if possible, and the competing interpretations. Ask the user instead of leaving unexplained uncertainty in the final paper.
+- Ensure the marking scheme matches final numbering exactly when a marking scheme is requested.
+- For diagrams, refer to them consistently as Diagram A, B, C, etc.
+
+## Required Clarifications
+
+Ask the user before proceeding when any of the following is missing:
+
+- subject
+- class level
+- authority source
+- sample layout path if layout matching matters
+- exact marks pattern for non-Math/non-English subjects
+- desired final format if not obvious
+- final interpretation of handwritten items that remain ambiguous after a multimodal-first extraction pass and contextual inference
+
+## Safe Revision Rules
+
+When updating an already-generated paper:
+
+1. revise the editable source first
+2. revise the marking scheme next if numbering/marks changed
+3. rerun validation/verification if answers, wording, or diagrams changed
+4. rerender DOCX last
+
+## Reference
+
+Load and follow [references/workflow-rulebook.md](references/workflow-rulebook.md) when you need the exact house style details.