@trespies-source/dojo-genesis-plugin 1.0.0 → 1.0.2

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { PluginAPI } from "./tests/__mocks__/openclaw-types.js";
+import type { PluginAPI } from "openclaw";
 declare const _default: {
     id: string;
     name: string;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;;;;;;;;;;;;;;kBAuBrD,SAAS;;AAfzB,wBA8BE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;;;;;;;;;;;;;;kBAuB1B,SAAS;;AAfzB,wBA8BE"}

package/dist/index.js

@@ -1,4 +1,4 @@
-import { registerPluginHooksFromDir } from "./tests/__mocks__/openclaw-types.js";
+import { registerPluginHooksFromDir } from "openclaw";
 import { registerDojoCommands } from "./src/commands/router.js";
 import { registerOrchestrationTools } from "./src/orchestration/tool-registry.js";
 import { initStateManager } from "./src/state/manager.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAClF,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,eAAe;IACb,EAAE,EAAE,qBAAqB;IACzB,IAAI,EAAE,cAAc;IAEpB,YAAY,EAAE;QACZ,IAAI,EAAE,QAAiB;QACvB,UAAU,EAAE;YACV,WAAW,EAAE;gBACX,IAAI,EAAE,QAAiB;gBACvB,OAAO,EAAE,qBAAqB;gBAC9B,WAAW,EAAE,4CAA4C;aAC1D;SACF;KACF;IAED,QAAQ,CAAC,GAAc;QACrB,IAAI,QAAgB,CAAC;QACrB,IAAI,CAAC;YACH,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC;QACtE,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,WAAW,CAAC,CAAC;QAC1C,CAAC;QAED,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAC3B,oBAAoB,CAAC,GAAG,CAAC,CAAC;QAC1B,0BAA0B,CAAC,GAAG,CAAC,CAAC;QAChC,0BAA0B,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAE3C,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;IACrD,CAAC;CACF,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAClF,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,eAAe;IACb,EAAE,EAAE,qBAAqB;IACzB,IAAI,EAAE,cAAc;IAEpB,YAAY,EAAE;QACZ,IAAI,EAAE,QAAiB;QACvB,UAAU,EAAE;YACV,WAAW,EAAE;gBACX,IAAI,EAAE,QAAiB;gBACvB,OAAO,EAAE,qBAAqB;gBAC9B,WAAW,EAAE,4CAA4C;aAC1D;SACF;KACF;IAED,QAAQ,CAAC,GAAc;QACrB,IAAI,QAAgB,CAAC;QACrB,IAAI,CAAC;YACH,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC;QACtE,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,WAAW,CAAC,CAAC;QAC1C,CAAC;QAED,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAC3B,oBAAoB,CAAC,GAAG,CAAC,CAAC;QAC1B,0BAA0B,CAAC,GAAG,CAAC,CAAC;QAChC,0BAA0B,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAE3C,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;IACrD,CAAC;CACF,CAAC"}

package/index.ts

@@ -0,0 +1,39 @@
+import type { PluginAPI } from "openclaw";
+import { registerPluginHooksFromDir } from "openclaw";
+import { registerDojoCommands } from "./src/commands/router.js";
+import { registerOrchestrationTools } from "./src/orchestration/tool-registry.js";
+import { initStateManager } from "./src/state/manager.js";
+import { homedir } from "os";
+import { join } from "path";
+
+export default {
+  id: "dojo-genesis-plugin",
+  name: "Dojo Genesis",
+
+  configSchema: {
+    type: "object" as const,
+    properties: {
+      projectsDir: {
+        type: "string" as const,
+        default: "dojo-genesis-plugin",
+        description: "State directory name under OpenClaw config",
+      },
+    },
+  },
+
+  register(api: PluginAPI) {
+    let stateDir: string;
+    try {
+      stateDir = api.runtime.state.resolveStateDir("dojo-genesis-plugin");
+    } catch {
+      stateDir = join(homedir(), ".openclaw");
+    }
+
+    initStateManager(stateDir);
+    registerDojoCommands(api);
+    registerOrchestrationTools(api);
+    registerPluginHooksFromDir(api, "./hooks");
+
+    api.logger.info("Dojo Genesis plugin initialized");
+  },
+};

package/openclaw.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Type declarations for the openclaw runtime package.
+ * The openclaw package does not ship its own .d.ts files,
+ * so we declare the subset of the API surface that this plugin uses.
+ */
+declare module "openclaw" {
+  export interface PluginLogger {
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+  }
+
+  export interface PluginRuntime {
+    state: {
+      resolveStateDir(pluginId: string): string;
+    };
+  }
+
+  export interface CommandContext {
+    args?: string;
+  }
+
+  export interface CommandRegistration {
+    name: string;
+    description: string;
+    handler: (ctx: CommandContext) => { text: string } | Promise<{ text: string }>;
+  }
+
+  export interface ToolResult {
+    content: Array<{ type: string; text: string }>;
+  }
+
+  export interface ToolRegistration {
+    name: string;
+    description: string;
+    parameters: unknown;
+    execute: (id: string, params: Record<string, unknown>) => Promise<ToolResult>;
+  }
+
+  export interface PluginAPI {
+    registerCommand(cmd: CommandRegistration): void;
+    registerTool(tool: ToolRegistration): void;
+    runtime: PluginRuntime;
+    logger: PluginLogger;
+  }
+
+  export interface HookEvent {
+    type: string;
+    action?: string;
+    messages: string[];
+    context?: Record<string, unknown>;
+  }
+
+  export type HookHandler = (event: HookEvent) => Promise<void> | void;
+
+  export function registerPluginHooksFromDir(api: PluginAPI, dir: string): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trespies-source/dojo-genesis-plugin",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Specification-driven development orchestration for OpenClaw",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,6 +9,9 @@
     ".": "./dist/index.js"
   },
   "files": [
+    "index.ts",
+    "openclaw.d.ts",
+    "src/",
     "dist/",
     "skills/",
     "hooks/",
@@ -18,7 +21,9 @@
     "CHANGELOG.md"
   ],
   "openclaw": {
-    "extensions": "index.ts"
+    "extensions": [
+      "./index.ts"
+    ]
   },
   "scripts": {
     "build": "tsc",

package/src/commands/archive.ts

@@ -0,0 +1,25 @@
+import { stateManager } from "../state/manager.js";
+
+export async function handleArchive(args: string[]): Promise<{ text: string }> {
+  const name = args[0];
+  if (!name) {
+    return { text: "Project name is required. Usage: `/dojo archive <name>`" };
+  }
+
+  const global = await stateManager.getGlobalState();
+  const meta = global.projects.find((p) => p.id === name);
+
+  if (!meta) {
+    return { text: `Project \`${name}\` not found.` };
+  }
+
+  if (meta.archived) {
+    return { text: `Project \`${name}\` is already archived.` };
+  }
+
+  await stateManager.archiveProject(name);
+
+  return {
+    text: `**Project archived:** \`${name}\`\n\nThe project files remain on disk. It will no longer appear in \`/dojo list\` (use \`--all\` to see archived projects).`,
+  };
+}

package/src/commands/init.ts

@@ -0,0 +1,68 @@
+import { stateManager } from "../state/manager.js";
+import { validateProjectName } from "../utils/validation.js";
+import { writeTextFile, writeJsonFile, ensureDir } from "../utils/file-ops.js";
+import { generateProjectMd } from "../utils/markdown.js";
+import type { ProjectMetadata, ProjectState } from "../state/types.js";
+
+export async function handleInit(args: string[]): Promise<{ text: string }> {
+  const name = args[0];
+  const validation = validateProjectName(name);
+  if (!validation.valid) {
+    return { text: `Invalid project name: ${validation.error}` };
+  }
+
+  const global = await stateManager.getGlobalState();
+  if (global.projects.some((p) => p.id === name && !p.archived)) {
+    return { text: `Project \`${name}\` already exists. Use \`/dojo switch ${name}\` to activate it.` };
+  }
+
+  const descIdx = args.indexOf("--desc");
+  const description =
+    descIdx >= 0 ? args.slice(descIdx + 1).join(" ").replace(/^"|"$/g, "") : "";
+
+  const now = new Date().toISOString();
+  const date = now.split("T")[0];
+
+  const meta: ProjectMetadata = {
+    id: name,
+    name,
+    description,
+    phase: "initialized",
+    createdAt: now,
+    lastAccessedAt: now,
+    archived: false,
+  };
+
+  const state: ProjectState = {
+    projectId: name,
+    phase: "initialized",
+    tracks: [],
+    decisions: [],
+    specs: [],
+    artifacts: [],
+    currentTrack: null,
+    lastSkill: "",
+    pendingAction: null,
+    activityLog: [{ timestamp: now, action: "command:init", summary: "Project created" }],
+    lastUpdated: now,
+  };
+
+  const projectDir = `${stateManager.getBasePath()}/projects/${name}`;
+  await ensureDir(projectDir);
+  await ensureDir(`${projectDir}/scouts`);
+  await ensureDir(`${projectDir}/specs`);
+  await ensureDir(`${projectDir}/prompts`);
+  await ensureDir(`${projectDir}/retros`);
+  await ensureDir(`${projectDir}/tracks`);
+  await ensureDir(`${projectDir}/artifacts`);
+
+  await writeTextFile(`${projectDir}/PROJECT.md`, generateProjectMd(name, description, date));
+  await writeTextFile(`${projectDir}/decisions.md`, `# Decision Log: ${name}\n\n---\n\n`);
+  await writeJsonFile(`${projectDir}/state.json`, state);
+
+  await stateManager.addProject(meta);
+
+  return {
+    text: `**Project created:** \`${name}\`\n\n**Phase:** initialized\n**Active:** yes\n\nNext: Run \`/dojo scout <tension>\` to start scouting.`,
+  };
+}

package/src/commands/list.ts

@@ -0,0 +1,11 @@
+import { stateManager } from "../state/manager.js";
+import { formatProjectList } from "../ui/chat-formatter.js";
+
+export async function handleList(args: string[]): Promise<{ text: string }> {
+  const showArchived = args.includes("--all");
+  const global = await stateManager.getGlobalState();
+
+  const table = formatProjectList(global.projects, showArchived, global.activeProjectId);
+
+  return { text: table };
+}

package/src/commands/router.ts

@@ -0,0 +1,91 @@
+import type { PluginAPI } from "../../tests/__mocks__/openclaw-types.js";
+import { handleInit } from "./init.js";
+import { handleSwitch } from "./switch.js";
+import { handleStatus } from "./status.js";
+import { handleList } from "./list.js";
+import { handleArchive } from "./archive.js";
+import { handleSkillInvoke } from "./skill-invoke.js";
+import { SKILL_CATALOG, listSkills } from "../skills/catalog.js";
+
+// Keep shorthand aliases for the core pipeline
+const PIPELINE_SHORTCUTS: Record<string, string> = {
+  scout: "strategic-scout",
+  spec: "release-specification",
+  tracks: "parallel-tracks",
+  commission: "implementation-prompt",
+  retro: "retrospective",
+};
+
+const HELP_TEXT = `**Dojo Genesis** — Specification-driven development orchestration
+
+**Project Management:**
+\`/dojo init <name>\` — Create a new project
+\`/dojo switch <name>\` — Switch active project
+\`/dojo status\` — Show current project status
+\`/dojo list\` — List all projects
+\`/dojo archive <name>\` — Archive a project
+
+**Core Pipeline:**
+\`/dojo scout <tension>\` — Strategic scout
+\`/dojo spec <feature>\` — Release specification
+\`/dojo tracks\` — Parallel track decomposition
+\`/dojo commission\` — Implementation prompts
+\`/dojo retro\` — Retrospective
+
+**Skill Catalog (40 skills):**
+\`/dojo run <skill-name> [args]\` — Run any skill
+\`/dojo skills [category]\` — Browse available skills
+
+Use \`@project-name\` to target a specific project.`;
+
+export function registerDojoCommands(api: PluginAPI): void {
+  api.registerCommand({
+    name: "dojo",
+    description: "Dojo Genesis: specification-driven development orchestration",
+    handler: (ctx) => {
+      const args = (ctx.args || "").trim().split(/\s+/).filter(Boolean);
+      const subcommand = args[0]?.toLowerCase();
+
+      switch (subcommand) {
+        case "init":
+          return handleInit(args.slice(1));
+        case "switch":
+          return handleSwitch(args.slice(1));
+        case "status":
+          return handleStatus(args.slice(1));
+        case "list":
+          return handleList(args.slice(1));
+        case "archive":
+          return handleArchive(args.slice(1));
+
+        case "scout":
+        case "spec":
+        case "tracks":
+        case "commission":
+        case "retro":
+          return handleSkillInvoke(PIPELINE_SHORTCUTS[subcommand], args.slice(1));
+
+        case "run": {
+          const skillName = args[1];
+          if (!skillName || !SKILL_CATALOG[skillName]) {
+            return {
+              text: `Unknown skill: \`${skillName || "(none)"}\`. Run \`/dojo skills\` for available skills.`,
+            };
+          }
+          return handleSkillInvoke(skillName, args.slice(2));
+        }
+
+        case "skills": {
+          const category = args[1];
+          return { text: listSkills(category) };
+        }
+
+        case "help":
+        case undefined:
+          return { text: HELP_TEXT };
+        default:
+          return { text: `Unknown command: \`${subcommand}\`. Run \`/dojo help\` for available commands.` };
+      }
+    },
+  });
+}

package/src/commands/skill-invoke.ts

@@ -0,0 +1,34 @@
+import { stateManager } from "../state/manager.js";
+import type { PendingAction } from "../state/types.js";
+
+export async function handleSkillInvoke(
+  skillName: string,
+  args: string[],
+): Promise<{ text: string }> {
+  const atProject = args.find((a) => a.startsWith("@"));
+  const remainingArgs = args.filter((a) => !a.startsWith("@"));
+  const projectId = atProject
+    ? atProject.slice(1)
+    : (await stateManager.getGlobalState()).activeProjectId;
+
+  if (!projectId) {
+    return { text: "No active project. Run `/dojo init <name>` first." };
+  }
+
+  const state = await stateManager.getProjectState(projectId);
+  if (!state) {
+    return { text: `Project \`${projectId}\` not found.` };
+  }
+
+  const pendingAction: PendingAction = {
+    skill: skillName,
+    args: remainingArgs.join(" "),
+    requestedAt: new Date().toISOString(),
+  };
+  await stateManager.updateProjectState(projectId, { pendingAction });
+  await stateManager.addActivity(projectId, `command:${skillName}`, `Requested ${skillName}`);
+
+  return {
+    text: `**Starting ${skillName}** for project \`${projectId}\` (phase: ${state.phase})\n\nThe agent will pick up this request and run the skill with your project context.`,
+  };
+}

package/src/commands/status.ts

@@ -0,0 +1,51 @@
+import { stateManager } from "../state/manager.js";
+import { formatPhase, formatDate, formatTrackTable } from "../ui/chat-formatter.js";
+import type { DojoPhase } from "../state/types.js";
+
+export async function handleStatus(args: string[]): Promise<{ text: string }> {
+  const atProject = args.find((a) => a.startsWith("@"));
+  const projectId = atProject?.slice(1) || undefined;
+  const state = await stateManager.getProjectState(projectId);
+
+  if (!state) {
+    return { text: "No active project. Run `/dojo init <name>` to create one." };
+  }
+
+  const recentActivity = state.activityLog.slice(0, 5);
+  const nextAction = suggestNextAction(state.phase);
+
+  let output = `**Project:** \`${state.projectId}\`\n`;
+  output += `**Phase:** ${formatPhase(state.phase)}\n`;
+  output += `**Last updated:** ${formatDate(state.lastUpdated)}\n\n`;
+
+  if (state.tracks.length > 0) {
+    output += `**Tracks:**\n${formatTrackTable(state.tracks)}\n\n`;
+  }
+
+  if (recentActivity.length > 0) {
+    output += `**Recent activity:**\n`;
+    for (const entry of recentActivity) {
+      output += `- ${formatDate(entry.timestamp)} — ${entry.summary}\n`;
+    }
+    output += "\n";
+  }
+
+  if (nextAction) {
+    output += `**Suggested next:** ${nextAction}`;
+  }
+
+  return { text: output };
+}
+
+function suggestNextAction(phase: DojoPhase): string {
+  const suggestions: Record<string, string> = {
+    initialized: "`/dojo scout <tension>` — Start with a strategic scout",
+    scouting: "`/dojo spec <feature>` — Write a release specification",
+    specifying: "`/dojo tracks` — Decompose into parallel tracks",
+    decomposing: "`/dojo commission` — Generate implementation prompts",
+    commissioning: "Hand off prompts to implementation agents",
+    implementing: "`/dojo retro` — Run a retrospective when done",
+    retrospective: "`/dojo init <name>` — Start a new project, or continue iterating",
+  };
+  return suggestions[phase] || "";
+}

package/src/commands/switch.ts

@@ -0,0 +1,25 @@
+import { stateManager } from "../state/manager.js";
+
+export async function handleSwitch(args: string[]): Promise<{ text: string }> {
+  const name = args[0];
+  if (!name) {
+    return { text: "Project name is required. Usage: `/dojo switch <name>`" };
+  }
+
+  const global = await stateManager.getGlobalState();
+  const meta = global.projects.find((p) => p.id === name);
+
+  if (!meta) {
+    return { text: `Project \`${name}\` not found.` };
+  }
+
+  if (meta.archived) {
+    return { text: `Project \`${name}\` is archived. Unarchive it first before switching.` };
+  }
+
+  await stateManager.setActiveProject(name);
+
+  return {
+    text: `**Switched to:** \`${name}\`\n\n**Phase:** ${meta.phase}`,
+  };
+}

package/src/orchestration/tool-registry.ts

@@ -0,0 +1,210 @@
+import { Type } from "@sinclair/typebox";
+import { stateManager } from "../state/manager.js";
+import { validateOutputDir, sanitizeFilename } from "../utils/validation.js";
+import { writeTextFile, ensureDir } from "../utils/file-ops.js";
+import type { DojoPhase } from "../state/types.js";
+
+interface ToolResult {
+  content: Array<{ type: string; text: string }>;
+}
+
+interface ToolRegistration {
+  name: string;
+  description: string;
+  parameters: unknown;
+  execute: (id: string, params: Record<string, unknown>) => Promise<ToolResult>;
+}
+
+interface ToolRegistrar {
+  registerTool(tool: ToolRegistration): void;
+}
+
+function jsonResult(data: unknown): ToolResult {
+  return { content: [{ type: "text", text: JSON.stringify(data) }] };
+}
+
+export function registerOrchestrationTools(api: ToolRegistrar): void {
+  api.registerTool({
+    name: "dojo_get_context",
+    description:
+      "Get the active Dojo Genesis project context including phase, tracks, decisions, and recent activity. Call this at the start of any skill execution to check if a project is active.",
+    parameters: Type.Object({
+      projectId: Type.Optional(
+        Type.String({ description: "Target a specific project instead of the active one" }),
+      ),
+    }),
+    async execute(_id, params) {
+      const state = await stateManager.getProjectState(params.projectId as string | undefined);
+      if (!state) {
+        return jsonResult({ active: false, message: "No active project" });
+      }
+
+      return jsonResult({
+        active: true,
+        projectId: state.projectId,
+        phase: state.phase,
+        tracks: state.tracks,
+        decisions: state.decisions.map((d) => ({ date: d.date, topic: d.topic })),
+        specs: state.specs,
+        currentTrack: state.currentTrack,
+        lastSkill: state.lastSkill,
+        recentActivity: state.activityLog.slice(0, 10),
+      });
+    },
+  });
+
+  api.registerTool({
+    name: "dojo_save_artifact",
+    description:
+      "Save a skill output as a markdown file in the active project directory. Use this after completing a skill to persist the results.",
+    parameters: Type.Object({
+      filename: Type.String({
+        description: "Output filename (e.g., '2026-02-12_scout_build-native.md')",
+      }),
+      content: Type.String({ description: "Full markdown content to save" }),
+      outputDir: Type.String({
+        description: "Subdirectory: scouts, specs, prompts, retros, tracks, or artifacts",
+      }),
+      projectId: Type.Optional(Type.String({ description: "Target specific project" })),
+    }),
+    async execute(_id, params) {
+      const outputDir = params.outputDir as string;
+      if (!validateOutputDir(outputDir)) {
+        return jsonResult({ error: `Invalid output directory: ${outputDir}` });
+      }
+
+      const global = await stateManager.getGlobalState();
+      const id = (params.projectId as string | undefined) || global.activeProjectId;
+      if (!id) {
+        return jsonResult({ error: "No active project" });
+      }
+
+      const safeName = sanitizeFilename(params.filename as string);
+      const basePath = stateManager.getBasePath();
+      const dir = `${basePath}/projects/${id}/${outputDir}`;
+      const filePath = `${dir}/${safeName}`;
+
+      await ensureDir(dir);
+      await writeTextFile(filePath, params.content as string);
+
+      const state = await stateManager.getProjectState(id);
+      if (state) {
+        state.artifacts.push({
+          category: outputDir,
+          filename: safeName,
+          createdAt: new Date().toISOString(),
+          skill: state.lastSkill || "unknown",
+        });
+        await stateManager.updateProjectState(id, { artifacts: state.artifacts });
+        await stateManager.addActivity(
+          id,
+          `artifact:${outputDir}`,
+          `Saved ${safeName} to ${outputDir}/`,
+        );
+      }
+
+      return jsonResult({ saved: true, path: `${outputDir}/${safeName}` });
+    },
+  });
+
+  api.registerTool({
+    name: "dojo_update_state",
+    description:
+      "Update the active project's phase, track status, or other state. Use this after completing a skill to advance the project workflow.",
+    parameters: Type.Object({
+      phase: Type.Optional(
+        Type.String({
+          description:
+            "New project phase (initialized, scouting, specifying, decomposing, commissioning, implementing, retrospective)",
+        }),
+      ),
+      lastSkill: Type.Optional(
+        Type.String({ description: "Name of the skill that just ran" }),
+      ),
+      currentTrack: Type.Optional(
+        Type.String({ description: "Set the current active track" }),
+      ),
+      addTrack: Type.Optional(
+        Type.Object({
+          id: Type.String(),
+          name: Type.String(),
+          dependencies: Type.Optional(Type.Array(Type.String())),
+        }),
+      ),
+      addDecision: Type.Optional(
+        Type.Object({
+          topic: Type.String(),
+          file: Type.String(),
+        }),
+      ),
+      addSpec: Type.Optional(
+        Type.Object({
+          version: Type.String(),
+          file: Type.String(),
+        }),
+      ),
+      projectId: Type.Optional(Type.String({ description: "Target specific project" })),
+    }),
+    async execute(_id, params) {
+      const global = await stateManager.getGlobalState();
+      const id = (params.projectId as string | undefined) || global.activeProjectId;
+      if (!id) {
+        return jsonResult({ error: "No active project" });
+      }
+
+      const state = await stateManager.getProjectState(id);
+      if (!state) {
+        return jsonResult({ error: `Project not found: ${id}` });
+      }
+
+      const updates: Record<string, unknown> = {};
+
+      if (params.phase) updates.phase = params.phase as DojoPhase;
+      if (params.lastSkill) updates.lastSkill = params.lastSkill;
+      if (params.currentTrack) updates.currentTrack = params.currentTrack;
+
+      if (params.addTrack) {
+        const track = params.addTrack as { id: string; name: string; dependencies?: string[] };
+        state.tracks.push({
+          id: track.id,
+          name: track.name,
+          status: "pending",
+          dependencies: track.dependencies || [],
+          promptFile: null,
+        });
+        updates.tracks = state.tracks;
+      }
+
+      if (params.addDecision) {
+        const decision = params.addDecision as { topic: string; file: string };
+        state.decisions.push({
+          date: new Date().toISOString().split("T")[0],
+          topic: decision.topic,
+          file: decision.file,
+        });
+        updates.decisions = state.decisions;
+      }
+
+      if (params.addSpec) {
+        const spec = params.addSpec as { version: string; file: string };
+        state.specs.push({
+          version: spec.version,
+          file: spec.file,
+        });
+        updates.specs = state.specs;
+      }
+
+      await stateManager.updateProjectState(id, updates);
+
+      if (params.lastSkill) {
+        await stateManager.addActivity(
+          id,
+          `skill:${params.lastSkill}`,
+          `${params.lastSkill} completed`,
+        );
+      }
+
+      return jsonResult({ updated: true, phase: (params.phase as string) || state.phase });
+    },
+  });
+}

package/src/skills/catalog.ts

@@ -0,0 +1,269 @@
+export interface SkillEntry {
+  name: string;
+  category: string;
+  description: string;
+}
+
+export const SKILL_CATALOG: Record<string, SkillEntry> = {
+  // Pipeline (also available as /dojo scout, spec, tracks, commission, retro)
+  "strategic-scout": {
+    name: "strategic-scout",
+    category: "pipeline",
+    description: "Explore strategic tensions and scout multiple routes",
+  },
+  "release-specification": {
+    name: "release-specification",
+    category: "pipeline",
+    description: "Write a production-ready release specification",
+  },
+  "parallel-tracks": {
+    name: "parallel-tracks",
+    category: "pipeline",
+    description: "Decompose specs into independent parallel tracks",
+  },
+  "implementation-prompt": {
+    name: "implementation-prompt",
+    category: "pipeline",
+    description: "Generate structured implementation prompts",
+  },
+  "retrospective": {
+    name: "retrospective",
+    category: "pipeline",
+    description: "Reflect on what went well, what was hard, what to improve",
+  },
+
+  // Workflow
+  "iterative-scouting": {
+    name: "iterative-scouting",
+    category: "workflow",
+    description: "Iterate scout cycles with reframes",
+  },
+  "strategic-to-tactical-workflow": {
+    name: "strategic-to-tactical-workflow",
+    category: "workflow",
+    description: "Full scout → spec → commission pipeline",
+  },
+  "pre-implementation-checklist": {
+    name: "pre-implementation-checklist",
+    category: "workflow",
+    description: "Verify specs are ready before commissioning",
+  },
+  "context-ingestion": {
+    name: "context-ingestion",
+    category: "workflow",
+    description: "Create plans grounded in uploaded files",
+  },
+  "frontend-from-backend": {
+    name: "frontend-from-backend",
+    category: "workflow",
+    description: "Write frontend specs from backend architecture",
+  },
+  "spec-constellation-to-prompt-suite": {
+    name: "spec-constellation-to-prompt-suite",
+    category: "workflow",
+    description: "Convert multiple specs into coordinated prompts",
+  },
+  "planning-with-files": {
+    name: "planning-with-files",
+    category: "workflow",
+    description: "Route file-based planning to specialized modes",
+  },
+
+  // Research
+  "research-modes": {
+    name: "research-modes",
+    category: "research",
+    description: "Deep and wide research with structured approaches",
+  },
+  "research-synthesis": {
+    name: "research-synthesis",
+    category: "research",
+    description: "Synthesize multiple sources into actionable insights",
+  },
+  "project-exploration": {
+    name: "project-exploration",
+    category: "research",
+    description: "Explore new projects to assess collaboration potential",
+  },
+  "era-architecture": {
+    name: "era-architecture",
+    category: "research",
+    description: "Architect multi-release eras with shared vocabulary",
+  },
+  "repo-context-sync": {
+    name: "repo-context-sync",
+    category: "research",
+    description: "Sync and extract context from repositories",
+  },
+  "documentation-audit": {
+    name: "documentation-audit",
+    category: "research",
+    description: "Audit documentation for drift and accuracy",
+  },
+  "health-audit": {
+    name: "health-audit",
+    category: "research",
+    description: "Comprehensive repository health check",
+  },
+
+  // Forge
+  "skill-creation": {
+    name: "skill-creation",
+    category: "forge",
+    description: "Create new reusable skills",
+  },
+  "skill-maintenance": {
+    name: "skill-maintenance",
+    category: "forge",
+    description: "Maintain skill health through systematic review",
+  },
+  "skill-audit-upgrade": {
+    name: "skill-audit-upgrade",
+    category: "forge",
+    description: "Audit and upgrade skills to quality standards",
+  },
+  "process-extraction": {
+    name: "process-extraction",
+    category: "forge",
+    description: "Transform workflows into reusable skills",
+  },
+
+  // Garden
+  "memory-garden": {
+    name: "memory-garden",
+    category: "garden",
+    description: "Write structured memory entries for context management",
+  },
+  "seed-extraction": {
+    name: "seed-extraction",
+    category: "garden",
+    description: "Extract reusable patterns from experiences",
+  },
+  "seed-library": {
+    name: "seed-library",
+    category: "garden",
+    description: "Access and apply Dojo Seed Patches",
+  },
+  "compression-ritual": {
+    name: "compression-ritual",
+    category: "garden",
+    description: "Distill conversation history into memory artifacts",
+  },
+  "seed-to-skill-converter": {
+    name: "seed-to-skill-converter",
+    category: "garden",
+    description: "Elevate proven seeds into full skills",
+  },
+
+  // Orchestration
+  "handoff-protocol": {
+    name: "handoff-protocol",
+    category: "orchestration",
+    description: "Hand off work between agents cleanly",
+  },
+  "decision-propagation": {
+    name: "decision-propagation",
+    category: "orchestration",
+    description: "Propagate decisions across document ecosystem",
+  },
+  "workspace-navigation": {
+    name: "workspace-navigation",
+    category: "orchestration",
+    description: "Navigate shared agent workspaces",
+  },
+  "agent-teaching": {
+    name: "agent-teaching",
+    category: "orchestration",
+    description: "Teach peers through shared practice",
+  },
+
+  // System
+  "semantic-clusters": {
+    name: "semantic-clusters",
+    category: "system",
+    description: "Map system capabilities with action-verb clusters",
+  },
+  "repo-status": {
+    name: "repo-status",
+    category: "system",
+    description: "Generate comprehensive repo status documents",
+  },
+  "status-template": {
+    name: "status-template",
+    category: "system",
+    description: "Write status docs using 10-section template",
+  },
+  "status-writing": {
+    name: "status-writing",
+    category: "system",
+    description: "Write and update STATUS.md files",
+  },
+
+  // Tools
+  "patient-learning-protocol": {
+    name: "patient-learning-protocol",
+    category: "tools",
+    description: "Learn at the pace of understanding",
+  },
+  "file-management": {
+    name: "file-management",
+    category: "tools",
+    description: "Organize files and directories flexibly",
+  },
+  "product-positioning": {
+    name: "product-positioning",
+    category: "tools",
+    description: "Reframe binary product decisions",
+  },
+  "multi-surface-strategy": {
+    name: "multi-surface-strategy",
+    category: "tools",
+    description: "Design coherent multi-surface strategies",
+  },
+};
+
+export const CATEGORIES = [
+  "pipeline",
+  "workflow",
+  "research",
+  "forge",
+  "garden",
+  "orchestration",
+  "system",
+  "tools",
+] as const;
+
+export function listSkills(category?: string): string {
+  const entries = Object.values(SKILL_CATALOG);
+  const filtered = category
+    ? entries.filter((e) => e.category === category)
+    : entries;
+
+  if (filtered.length === 0) {
+    return category
+      ? `No skills in category "${category}". Available: ${CATEGORIES.join(", ")}`
+      : "No skills found.";
+  }
+
+  const grouped: Record<string, SkillEntry[]> = {};
+  for (const entry of filtered) {
+    (grouped[entry.category] ??= []).push(entry);
+  }
+
+  const lines: string[] = ["**Dojo Genesis Skill Catalog**\n"];
+  for (const cat of CATEGORIES) {
+    if (!grouped[cat]) continue;
+    const label =
+      cat === "pipeline"
+        ? `${cat} (shorthand: /dojo scout|spec|tracks|commission|retro)`
+        : cat;
+    lines.push(`**${label}:**`);
+    for (const s of grouped[cat]) {
+      lines.push(`  \`${s.name}\` — ${s.description}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("Run any skill with: `/dojo run <skill-name> [args]`");
+  return lines.join("\n");
+}

package/src/state/manager.ts

@@ -0,0 +1,134 @@
+import { readJsonFile, writeJsonFile, ensureDir } from "../utils/file-ops.js";
+import type { GlobalState, ProjectState, ProjectMetadata } from "./types.js";
+import { checkSchemaVersion } from "./migrations.js";
+
+const SCHEMA_VERSION = "1.0.0";
+const MAX_ACTIVITY_LOG = 50;
+
+export class DojoStateManager {
+  private basePath: string;
+  private globalCache: GlobalState | null = null;
+  private projectCache: Map<string, ProjectState> = new Map();
+
+  constructor(configDir: string) {
+    this.basePath = `${configDir}/dojo-genesis-plugin`;
+  }
+
+  getBasePath(): string {
+    return this.basePath;
+  }
+
+  async getGlobalState(): Promise<GlobalState> {
+    if (!this.globalCache) {
+      await ensureDir(this.basePath);
+      const loaded = await readJsonFile<GlobalState>(
+        `${this.basePath}/global-state.json`,
+        {
+          version: SCHEMA_VERSION,
+          activeProjectId: null,
+          projects: [],
+          lastUpdated: new Date().toISOString(),
+        },
+      );
+      this.globalCache = checkSchemaVersion(loaded);
+    }
+    return this.globalCache;
+  }
+
+  async setActiveProject(projectId: string | null): Promise<void> {
+    const state = await this.getGlobalState();
+    state.activeProjectId = projectId;
+    state.lastUpdated = new Date().toISOString();
+    if (projectId) {
+      const meta = state.projects.find((p) => p.id === projectId);
+      if (meta) meta.lastAccessedAt = state.lastUpdated;
+    }
+    await this.saveGlobalState(state);
+  }
+
+  async addProject(meta: ProjectMetadata): Promise<void> {
+    const state = await this.getGlobalState();
+    state.projects.push(meta);
+    state.activeProjectId = meta.id;
+    state.lastUpdated = new Date().toISOString();
+    await this.saveGlobalState(state);
+  }
+
+  async getProjectState(projectId?: string): Promise<ProjectState | null> {
+    const global = await this.getGlobalState();
+    const id = projectId || global.activeProjectId;
+    if (!id) return null;
+
+    if (!this.projectCache.has(id)) {
+      const state = await readJsonFile<ProjectState | null>(
+        `${this.basePath}/projects/${id}/state.json`,
+        null,
+      );
+      if (state) this.projectCache.set(id, state);
+      return state;
+    }
+    return this.projectCache.get(id) || null;
+  }
+
+  async updateProjectState(projectId: string, update: Partial<ProjectState>): Promise<void> {
+    const current = await this.getProjectState(projectId);
+    if (!current) throw new Error(`Project not found: ${projectId}`);
+
+    const updated: ProjectState = {
+      ...current,
+      ...update,
+      lastUpdated: new Date().toISOString(),
+    };
+    await writeJsonFile(`${this.basePath}/projects/${projectId}/state.json`, updated);
+    this.projectCache.set(projectId, updated);
+
+    const global = await this.getGlobalState();
+    const meta = global.projects.find((p) => p.id === projectId);
+    if (meta) {
+      meta.phase = updated.phase;
+      meta.lastAccessedAt = updated.lastUpdated;
+      await this.saveGlobalState(global);
+    }
+  }
+
+  async archiveProject(projectId: string): Promise<boolean> {
+    const state = await this.getGlobalState();
+    const meta = state.projects.find((p) => p.id === projectId);
+    if (!meta) return false;
+    if (meta.archived) return false;
+
+    meta.archived = true;
+    meta.lastAccessedAt = new Date().toISOString();
+
+    if (state.activeProjectId === projectId) {
+      state.activeProjectId = null;
+    }
+
+    state.lastUpdated = new Date().toISOString();
+    await this.saveGlobalState(state);
+    return true;
+  }
+
+  async addActivity(projectId: string, action: string, summary: string): Promise<void> {
+    const state = await this.getProjectState(projectId);
+    if (!state) return;
+
+    state.activityLog = [
+      { timestamp: new Date().toISOString(), action, summary },
+      ...state.activityLog.slice(0, MAX_ACTIVITY_LOG - 1),
+    ];
+    await this.updateProjectState(projectId, { activityLog: state.activityLog });
+  }
+
+  private async saveGlobalState(state: GlobalState): Promise<void> {
+    await writeJsonFile(`${this.basePath}/global-state.json`, state);
+    this.globalCache = state;
+  }
+}
+
+export let stateManager: DojoStateManager;
+
+export function initStateManager(configDir: string): DojoStateManager {
+  stateManager = new DojoStateManager(configDir);
+  return stateManager;
+}

package/src/state/migrations.ts

@@ -0,0 +1,12 @@
+import type { GlobalState } from "./types.js";
+
+const CURRENT_VERSION = "1.0.0";
+
+export function checkSchemaVersion(state: GlobalState): GlobalState {
+  if (state.version !== CURRENT_VERSION) {
+    throw new Error(
+      `Unsupported schema version: ${state.version}. Expected ${CURRENT_VERSION}.`,
+    );
+  }
+  return state;
+}

package/src/state/types.ts

@@ -0,0 +1,77 @@
+export type DojoPhase =
+  | "initialized"
+  | "scouting"
+  | "specifying"
+  | "decomposing"
+  | "commissioning"
+  | "implementing"
+  | "retrospective";
+
+export interface GlobalState {
+  version: string;
+  activeProjectId: string | null;
+  projects: ProjectMetadata[];
+  lastUpdated: string;
+}
+
+export interface ProjectMetadata {
+  id: string;
+  name: string;
+  description: string;
+  phase: DojoPhase;
+  createdAt: string;
+  lastAccessedAt: string;
+  archived: boolean;
+}
+
+export interface PendingAction {
+  skill: string;
+  args: string;
+  requestedAt: string;
+}
+
+export interface ProjectState {
+  projectId: string;
+  phase: DojoPhase;
+  tracks: Track[];
+  decisions: DecisionRef[];
+  specs: SpecRef[];
+  artifacts: ArtifactRef[];
+  currentTrack: string | null;
+  lastSkill: string;
+  pendingAction: PendingAction | null;
+  activityLog: ActivityEntry[];
+  lastUpdated: string;
+}
+
+export interface Track {
+  id: string;
+  name: string;
+  status: "pending" | "in-progress" | "completed" | "blocked";
+  dependencies: string[];
+  promptFile: string | null;
+}
+
+export interface DecisionRef {
+  date: string;
+  topic: string;
+  file: string;
+}
+
+export interface SpecRef {
+  version: string;
+  file: string;
+}
+
+export interface ArtifactRef {
+  category: string;
+  filename: string;
+  createdAt: string;
+  skill: string;
+}
+
+export interface ActivityEntry {
+  timestamp: string;
+  action: string;
+  summary: string;
+}

package/src/ui/chat-formatter.ts

@@ -0,0 +1,48 @@
+import type { Track, DojoPhase } from "../state/types.js";
+
+const PHASE_INDICATOR: Record<DojoPhase, string> = {
+  initialized: "[ ]",
+  scouting: "[~]",
+  specifying: "[~]",
+  decomposing: "[~]",
+  commissioning: "[~]",
+  implementing: "[>]",
+  retrospective: "[*]",
+};
+
+export function formatPhase(phase: DojoPhase): string {
+  return `${PHASE_INDICATOR[phase] || "[ ]"} ${phase}`;
+}
+
+export function formatDate(iso: string): string {
+  return iso.split("T")[0];
+}
+
+export function formatTrackTable(tracks: Track[]): string {
+  if (tracks.length === 0) return "_No tracks defined._";
+
+  let table = "| Track | Name | Status | Dependencies |\n";
+  table += "|-------|------|--------|-------------|\n";
+  for (const t of tracks) {
+    const deps = t.dependencies.length > 0 ? t.dependencies.join(", ") : "none";
+    table += `| ${t.id} | ${t.name} | ${t.status} | ${deps} |\n`;
+  }
+  return table;
+}
+
+export function formatProjectList(
+  projects: Array<{ id: string; phase: string; lastAccessedAt: string; archived: boolean }>,
+  showArchived: boolean,
+  activeId: string | null,
+): string {
+  const visible = projects.filter(p => showArchived || !p.archived);
+  if (visible.length === 0) return "_No projects. Run `/dojo init <name>` to create one._";
+
+  let table = "| Project | Phase | Last Active | Active |\n";
+  table += "|---------|-------|-------------|--------|\n";
+  for (const p of visible) {
+    const active = p.id === activeId ? ">>>" : "";
+    table += `| ${p.id} | ${p.phase} | ${formatDate(p.lastAccessedAt)} | ${active} |\n`;
+  }
+  return table;
+}

package/src/utils/file-ops.ts

@@ -0,0 +1,39 @@
+import { promises as fs } from "fs";
+import { dirname } from "path";
+
+export async function readJsonFile<T>(path: string, defaultValue: T): Promise<T> {
+  try {
+    const raw = await fs.readFile(path, "utf-8");
+    return JSON.parse(raw) as T;
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return defaultValue;
+    throw err;
+  }
+}
+
+export async function writeJsonFile(path: string, data: unknown): Promise<void> {
+  await ensureDir(dirname(path));
+  const tmp = `${path}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(data, null, 2), "utf-8");
+  await fs.rename(tmp, path);
+}
+
+export async function writeTextFile(path: string, content: string): Promise<void> {
+  await ensureDir(dirname(path));
+  const tmp = `${path}.tmp`;
+  await fs.writeFile(tmp, content, "utf-8");
+  await fs.rename(tmp, path);
+}
+
+export async function ensureDir(dir: string): Promise<void> {
+  await fs.mkdir(dir, { recursive: true });
+}
+
+export async function fileExists(path: string): Promise<boolean> {
+  try {
+    await fs.access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/utils/markdown.ts

@@ -0,0 +1,12 @@
+export function generateProjectMd(name: string, description: string, date: string): string {
+  const descBlock = description ? `${description}\n\n` : "";
+  return (
+    `# ${name}\n\n` +
+    descBlock +
+    `**Phase:** initialized\n` +
+    `**Created:** ${date}\n\n` +
+    `---\n\n` +
+    `## Activity Log\n\n` +
+    `- ${date} — Project created\n`
+  );
+}

package/src/utils/validation.ts

@@ -0,0 +1,30 @@
+const PROJECT_NAME_REGEX = /^[a-z0-9][a-z0-9-]{1,63}$/;
+const DOUBLE_HYPHEN = /--/;
+
+export function validateProjectName(name: string): { valid: boolean; error?: string } {
+  if (!name) return { valid: false, error: "Project name is required" };
+  if (!PROJECT_NAME_REGEX.test(name)) {
+    return {
+      valid: false,
+      error: "Project name must be 2-64 chars, lowercase alphanumeric + hyphens, start with letter/number",
+    };
+  }
+  if (DOUBLE_HYPHEN.test(name)) {
+    return { valid: false, error: "Project name cannot contain consecutive hyphens" };
+  }
+  return { valid: true };
+}
+
+export function sanitizeFilename(input: string): string {
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9-_]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 128);
+}
+
+export function validateOutputDir(dir: string): boolean {
+  const allowed = ["scouts", "specs", "prompts", "retros", "tracks", "artifacts"];
+  return allowed.includes(dir);
+}