@smithers-orchestrator/cli 0.16.9 → 0.18.0

package/src/workflow-pack.js

@@ -1,10 +1,11 @@
 import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { generateAgentsTs } from "./agent-detection.js";
 /**
- * @typedef {{ force?: boolean; rootDir?: string; skipInstall?: boolean; }} InitOptions
+ * @typedef {{ force?: boolean; rootDir?: string; skipInstall?: boolean; agentsOnly?: boolean; }} InitOptions
  */
 /**
  * @typedef {{ status: "ok" | "skipped" | "failed"; reason?: string; }} InitInstallResult
@@ -15,6 +16,12 @@ import { generateAgentsTs } from "./agent-detection.js";
 /**
  * @typedef {{ command: string; description: string; }} WorkflowCta
  */
+/**
+ * @typedef {{ path: string; contents: string; preserveExisting?: boolean; }} TemplateFile
+ */
+
+const FALLBACK_SMITHERS_SPEC = "latest";
+const require = createRequire(import.meta.url);
 
 /**
  * @param {string} path
@@ -47,26 +54,33 @@ function readPackageVersion(path, fallback) {
     }
 }
 /**
- * Resolve `<spec>/package.json` via Node's module resolution (from this file's
- * location) and return its `version`. Uses `import.meta.resolve` so it works
- * whether the CLI is running from the monorepo checkout (deps under
- * `apps/cli/node_modules/`) or installed flat under a user's project
- * `node_modules/`. Falls back to the pin bundled at release time when the
- * package isn't installed in the user's project (typical for devDep-only
- * specs like `typescript` and `@types/*`).
+ * Resolve an installed dependency version from the current package layout.
  *
- * @param {string} spec
+ * @param {string} specifier
  * @param {string} fallback
  */
-function resolveDependencyVersion(spec, fallback) {
+function resolveInstalledPackageVersion(specifier, fallback) {
     try {
-        const url = import.meta.resolve(`${spec}/package.json`);
-        return readPackageVersion(fileURLToPath(url), fallback);
+        const resolved = require.resolve(`${specifier}/package.json`);
+        return readPackageVersion(resolved, fallback);
     }
     catch {
         return fallback;
     }
 }
+/**
+ * @returns {string | undefined}
+ */
+function readOwnPackageVersion() {
+    try {
+        const ownPackagePath = fileURLToPath(new URL("../package.json", import.meta.url));
+        const version = readJson(ownPackagePath).version;
+        return typeof version === "string" && version.length > 0 ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Pins shipped with this release for devDep-only specs that won't be in the
  * user's `node_modules` after `bunx smithers-orchestrator@latest init`. Bump
@@ -78,24 +92,29 @@ const BUNDLED_VERSION_PINS = {
     reactTypes: "19.2.14",
     reactDomTypes: "19.2.3",
     mdxTypes: "2.0.13",
+    nodeTypes: "25.6.0",
 };
 /**
  * @returns {DependencyVersions}
  */
 function readDependencyVersions() {
     return {
-        smithersVersion: readPackageVersion(fileURLToPath(new URL("../package.json", import.meta.url)), "0.0.0"),
-        zodVersion: resolveDependencyVersion("zod", BUNDLED_VERSION_PINS.zod),
-        typescriptVersion: resolveDependencyVersion("typescript", BUNDLED_VERSION_PINS.typescript),
-        reactTypesVersion: resolveDependencyVersion("@types/react", BUNDLED_VERSION_PINS.reactTypes),
-        reactDomTypesVersion: resolveDependencyVersion("@types/react-dom", BUNDLED_VERSION_PINS.reactDomTypes),
-        mdxTypesVersion: resolveDependencyVersion("@types/mdx", BUNDLED_VERSION_PINS.mdxTypes),
+        smithersVersion: readOwnPackageVersion(),
+        zodVersion: resolveInstalledPackageVersion("zod", BUNDLED_VERSION_PINS.zod),
+        typescriptVersion: resolveInstalledPackageVersion("typescript", BUNDLED_VERSION_PINS.typescript),
+        reactTypesVersion: resolveInstalledPackageVersion("@types/react", BUNDLED_VERSION_PINS.reactTypes),
+        reactDomTypesVersion: resolveInstalledPackageVersion("@types/react-dom", BUNDLED_VERSION_PINS.reactDomTypes),
+        mdxTypesVersion: resolveInstalledPackageVersion("@types/mdx", BUNDLED_VERSION_PINS.mdxTypes),
+        nodeTypesVersion: resolveInstalledPackageVersion("@types/node", BUNDLED_VERSION_PINS.nodeTypes),
     };
 }
 /**
  * @param {DependencyVersions} versions
  */
 function renderPackageJson(versions) {
+    const smithersSpec = versions.smithersVersion
+        ? `^${versions.smithersVersion}`
+        : FALLBACK_SMITHERS_SPEC;
     return JSON.stringify({
         name: "smithers-workflows",
         private: true,
@@ -108,7 +127,7 @@ function renderPackageJson(versions) {
         },
         dependencies: {
             skills: "github:mattpocock/skills",
-            "smithers-orchestrator": "latest",
+            "smithers-orchestrator": smithersSpec,
             zod: versions.zodVersion,
         },
         devDependencies: {
@@ -116,6 +135,7 @@ function renderPackageJson(versions) {
             "@types/react": versions.reactTypesVersion,
             "@types/react-dom": versions.reactDomTypesVersion,
             "@types/mdx": versions.mdxTypesVersion,
+            "@types/node": versions.nodeTypesVersion,
         },
     }, null, 2) + "\n";
 }
@@ -143,6 +163,104 @@ function renderTsconfig() {
         exclude: ["./executions/**/*"],
     }, null, 2) + "\n";
 }
+/**
+ * @returns {TemplateFile[]}
+ */
+function renderAgentScaffoldFiles() {
+    return [
+        {
+            path: ".smithers/agents/claude-code.ts",
+            preserveExisting: true,
+            contents: [
+                'import { ClaudeCodeAgent as SmithersClaudeCodeAgent } from "smithers-orchestrator";',
+                "",
+                '// Built-in Claude Code CLI agent (cliEngine: "claude-code").',
+                "// Tweak `model`, `cwd`, or uncomment extra options below to match your setup.",
+                "export const ClaudeCodeAgent = new SmithersClaudeCodeAgent({",
+                '  model: "claude-opus-4-6",',
+                "  cwd: process.cwd(),",
+                '  // systemPrompt: "Add shared instructions for every Claude run.",',
+                "  // timeoutMs: 10 * 60 * 1000,",
+                "  // dangerouslySkipPermissions: true,",
+                "});",
+                "",
+            ].join("\n"),
+        },
+        {
+            path: ".smithers/agents/codex.ts",
+            preserveExisting: true,
+            contents: [
+                'import { CodexAgent as SmithersCodexAgent } from "smithers-orchestrator";',
+                "",
+                '// Built-in Codex CLI agent (cliEngine: "codex").',
+                "// Tweak `model`, `cwd`, or uncomment extra options below to match your setup.",
+                "export const CodexAgent = new SmithersCodexAgent({",
+                '  model: "gpt-5.3-codex",',
+                "  cwd: process.cwd(),",
+                "  skipGitRepoCheck: true,",
+                '  // systemPrompt: "Add shared instructions for every Codex run.",',
+                '  // sandbox: "workspace-write",',
+                "  // fullAuto: true,",
+                "});",
+                "",
+            ].join("\n"),
+        },
+        {
+            path: ".smithers/agents/gemini.ts",
+            preserveExisting: true,
+            contents: [
+                'import { GeminiAgent as SmithersGeminiAgent } from "smithers-orchestrator";',
+                "",
+                '// Built-in Gemini CLI agent (cliEngine: "gemini").',
+                "// Tweak `model`, `cwd`, or uncomment extra options below to match your setup.",
+                "export const GeminiAgent = new SmithersGeminiAgent({",
+                '  model: "gemini-3.1-pro-preview",',
+                "  cwd: process.cwd(),",
+                '  // systemPrompt: "Add shared instructions for every Gemini run.",',
+                '  // approvalMode: "yolo",',
+                '  // allowedTools: ["read_file", "write_file"],',
+                "});",
+                "",
+            ].join("\n"),
+        },
+        {
+            path: ".smithers/agents/index.ts",
+            preserveExisting: true,
+            contents: [
+                'export { ClaudeCodeAgent } from "./claude-code";',
+                'export { CodexAgent } from "./codex";',
+                'export { GeminiAgent } from "./gemini";',
+                "",
+            ].join("\n"),
+        },
+        {
+            path: ".smithers/agents/README.md",
+            preserveExisting: true,
+            contents: [
+                "# Agent Config",
+                "",
+                "These files export the configured agent instances used by your Smithers workflows.",
+                "",
+                "- `claude-code.ts`, `codex.ts`, and `gemini.ts` are user-owned config.",
+                "- Edit them to pin models, set `cwd`, add a shared `systemPrompt`, or enable engine-specific flags.",
+                "- `index.ts` re-exports all three so root-level files can import from `./agents`.",
+                "",
+                "Examples:",
+                "",
+                "```ts",
+                'import { ClaudeCodeAgent } from "./agents";',
+                'import { CodexAgent } from "./agents/codex";',
+                "```",
+                "",
+                "Inside `.smithers/workflows/*`, use `../agents` or `../agents/<name>` instead.",
+                "",
+                "`smithers init` and `smithers init --agents-only` only create missing files in this directory.",
+                "Existing files here are left alone so your custom agent config is preserved.",
+                "",
+            ].join("\n"),
+        },
+    ];
+}
 /**
  * @returns {TemplateFile[]}
  */
@@ -486,6 +604,183 @@ function renderPrompts() {
                 "",
             ].join("\n"),
         },
+        {
+            path: ".smithers/prompts/mission-plan.mdx",
+            contents: [
+                "# Mission Plan",
+                "",
+                "You are the mission orchestrator for a long-running Smithers workflow.",
+                "Scope the goal with the user before execution. If critical requirements, constraints, or acceptance criteria are missing, ask one question at a time using the ask-user command from the instructions you were given.",
+                "",
+                "Design the mission as serial milestones with targeted parallelism inside each milestone.",
+                "Each milestone must be a meaningful checkpoint that can be validated before the next milestone begins.",
+                "Each feature should be narrow enough for a fresh worker session to execute without needing the full mission history.",
+                "Include explicit validation checks for every milestone: tests, lint/typecheck/build commands, integration checks, and UI/browser walkthroughs when the repo has an app surface.",
+                "Capture risks, assumptions, out-of-scope items, and anything the user should approve before work starts.",
+                "",
+                "REQUEST:",
+                "{props.prompt}",
+                "",
+                "LIMITS:",
+                "- Max milestones: {props.maxMilestones}",
+                "- Max features per milestone: {props.maxFeaturesPerMilestone}",
+                "",
+                "REQUIRED OUTPUT:",
+                "{props.schema}",
+                "",
+            ].join("\n"),
+        },
+        {
+            path: ".smithers/prompts/mission-worker.mdx",
+            contents: [
+                "# Mission Worker",
+                "",
+                "You are a focused feature worker in a larger mission. Treat this as a fresh context window: use the mission plan below, execute only your assigned feature, and keep handoff notes precise.",
+                "",
+                "Rules:",
+                "1. Stay within the assigned feature scope unless you must make a small adjacent change to keep the repo working.",
+                "2. Prefer existing repo patterns and run the most relevant checks you can.",
+                "3. Record files changed, commands run, unresolved issues, and reusable learnings for later workers.",
+                "4. If the feature cannot be completed, make the best safe partial progress and explain exactly what blocks it.",
+                "",
+                "MISSION GOAL:",
+                "{props.missionGoal}",
+                "",
+                "MILESTONE:",
+                "```json",
+                "{JSON.stringify(props.milestone, null, 2)}",
+                "```",
+                "",
+                "FEATURE:",
+                "```json",
+                "{JSON.stringify(props.feature, null, 2)}",
+                "```",
+                "",
+                "{props.previousSummary ? `PREVIOUS MILESTONE SUMMARY:\\n${props.previousSummary}` : \"\"}",
+                "",
+                "REQUIRED OUTPUT:",
+                "{props.schema}",
+                "",
+            ].join("\n"),
+        },
+        {
+            path: ".smithers/prompts/mission-integrate.mdx",
+            contents: [
+                "# Mission Integrate",
+                "",
+                "You are integrating feature-worker results for one milestone.",
+                "",
+                "{props.useWorktrees ? \"The feature work may live on per-feature worktree branches. Inspect the branches, merge successful work back into the main workspace, resolve conflicts carefully, and leave conflicted or unsafe branches unmerged with a clear explanation.\" : \"Feature workers ran in the main workspace. Inspect their results and make any small integration fixes needed before validation.\"}",
+                "",
+                "MISSION GOAL:",
+                "{props.missionGoal}",
+                "",
+                "MILESTONE:",
+                "```json",
+                "{JSON.stringify(props.milestone, null, 2)}",
+                "```",
+                "",
+                "FEATURE RESULTS:",
+                "```json",
+                "{JSON.stringify(props.results, null, 2)}",
+                "```",
+                "",
+                "REQUIRED OUTPUT:",
+                "{props.schema}",
+                "",
+            ].join("\n"),
+        },
+        {
+            path: ".smithers/prompts/mission-validate.mdx",
+            contents: [
+                "# Mission Validate",
+                "",
+                "You are a validation worker for a mission milestone.",
+                "Validate accumulated work before the orchestrator moves to the next milestone.",
+                "",
+                "Run the strongest checks that fit the repo: tests, lint, typecheck, build, smoke tests, and integration checks.",
+                "If the repo has a UI, launch it and exercise core flows like a user would. Check render correctness, navigation, state transitions, and obvious layout regressions.",
+                "If a check cannot run because the repo lacks commands or setup, report that as a validation limitation instead of inventing results.",
+                "",
+                "MISSION GOAL:",
+                "{props.missionGoal}",
+                "",
+                "MILESTONE:",
+                "```json",
+                "{JSON.stringify(props.milestone, null, 2)}",
+                "```",
+                "",
+                "INTEGRATION RESULT:",
+                "```json",
+                "{JSON.stringify(props.integration, null, 2)}",
+                "```",
+                "",
+                "{props.followUp ? `FOLLOW-UP RESULT:\\n${JSON.stringify(props.followUp, null, 2)}` : \"\"}",
+                "",
+                "REQUIRED OUTPUT:",
+                "{props.schema}",
+                "",
+            ].join("\n"),
+        },
+        {
+            path: ".smithers/prompts/mission-follow-up.mdx",
+            contents: [
+                "# Mission Follow-Up",
+                "",
+                "Validation found issues in the current milestone. Fix the concrete regressions and gaps before the mission proceeds.",
+                "Keep changes targeted. Do not begin the next milestone.",
+                "",
+                "MISSION GOAL:",
+                "{props.missionGoal}",
+                "",
+                "MILESTONE:",
+                "```json",
+                "{JSON.stringify(props.milestone, null, 2)}",
+                "```",
+                "",
+                "VALIDATION RESULT:",
+                "```json",
+                "{JSON.stringify(props.validation, null, 2)}",
+                "```",
+                "",
+                "REQUIRED OUTPUT:",
+                "{props.schema}",
+                "",
+            ].join("\n"),
+        },
+        {
+            path: ".smithers/prompts/mission-final.mdx",
+            contents: [
+                "# Mission Final Report",
+                "",
+                "Write the final mission report. Summarize what shipped, what was validated, what remains risky, and the recommended next actions.",
+                "Be concrete about files, commands, validation gaps, and any milestone that did not pass validation.",
+                "",
+                "MISSION PLAN:",
+                "```json",
+                "{JSON.stringify(props.plan, null, 2)}",
+                "```",
+                "",
+                "FEATURE RESULTS:",
+                "```json",
+                "{JSON.stringify(props.featureResults, null, 2)}",
+                "```",
+                "",
+                "INTEGRATION RESULTS:",
+                "```json",
+                "{JSON.stringify(props.integrationResults, null, 2)}",
+                "```",
+                "",
+                "VALIDATION RESULTS:",
+                "```json",
+                "{JSON.stringify(props.validationResults, null, 2)}",
+                "```",
+                "",
+                "REQUIRED OUTPUT:",
+                "{props.schema}",
+                "",
+            ].join("\n"),
+        },
         {
             path: ".smithers/prompts/tickets-create.mdx",
             contents: [
@@ -1870,6 +2165,440 @@ function renderWorkflows() {
             "  </Workflow>",
             "));",
         ]),
+        renderWorkflowFile("mission", "Mission", [
+            ...sharedImports,
+            'import AskUserInstructions from "../prompts/ask-user-instructions.mdx";',
+            'import MissionPlanPrompt from "../prompts/mission-plan.mdx";',
+            'import MissionWorkerPrompt from "../prompts/mission-worker.mdx";',
+            'import MissionIntegratePrompt from "../prompts/mission-integrate.mdx";',
+            'import MissionValidatePrompt from "../prompts/mission-validate.mdx";',
+            'import MissionFollowUpPrompt from "../prompts/mission-follow-up.mdx";',
+            'import MissionFinalPrompt from "../prompts/mission-final.mdx";',
+            "",
+            "const missionFeatureSchema = z.looseObject({",
+            '  id: z.string().default("feature"),',
+            '  title: z.string().default("Feature"),',
+            '  instructions: z.string().default("Complete the assigned feature."),',
+            "  files: z.array(z.string()).default([]),",
+            "  validation: z.array(z.string()).default([]),",
+            '  workerType: z.enum(["implementation", "test", "docs", "research"]).default("implementation"),',
+            "  canRunInParallel: z.boolean().default(true),",
+            "});",
+            "",
+            "const missionMilestoneSchema = z.looseObject({",
+            '  id: z.string().default("milestone"),',
+            '  title: z.string().default("Milestone"),',
+            '  objective: z.string().default("Complete this milestone."),',
+            "  features: z.array(missionFeatureSchema).default([]),",
+            "  validationPlan: z.array(z.string()).default([]),",
+            "});",
+            "",
+            "const missionPlanSchema = z.looseObject({",
+            '  goal: z.string().default(""),',
+            '  summary: z.string().default("Mission plan created."),',
+            "  milestones: z.array(missionMilestoneSchema).default([]),",
+            "  assumptions: z.array(z.string()).default([]),",
+            "  risks: z.array(z.string()).default([]),",
+            "  outOfScope: z.array(z.string()).default([]),",
+            '  approvalNotes: z.string().nullable().default(null),',
+            "});",
+            "",
+            "const missionApprovalSchema = z.looseObject({",
+            "  approved: z.boolean().default(false),",
+            "  note: z.string().nullable().default(null),",
+            "  decidedBy: z.string().nullable().default(null),",
+            "  decidedAt: z.string().nullable().default(null),",
+            "});",
+            "",
+            "const missionFeatureResultSchema = z.looseObject({",
+            '  featureId: z.string().default("feature"),',
+            '  status: z.enum(["success", "partial", "failed"]).default("partial"),',
+            '  summary: z.string().default("Feature worker completed."),',
+            "  filesChanged: z.array(z.string()).default([]),",
+            "  commandsRun: z.array(z.string()).default([]),",
+            "  blockers: z.array(z.string()).default([]),",
+            "  reusableLearnings: z.array(z.string()).default([]),",
+            "});",
+            "",
+            "const milestoneIntegrationSchema = z.looseObject({",
+            '  milestoneId: z.string().default("milestone"),',
+            '  status: z.enum(["integrated", "partial", "blocked"]).default("integrated"),',
+            '  summary: z.string().default("Milestone integrated."),',
+            "  mergedBranches: z.array(z.string()).default([]),",
+            "  conflictedBranches: z.array(z.string()).default([]),",
+            "  filesChanged: z.array(z.string()).default([]),",
+            "});",
+            "",
+            "const milestoneValidationSchema = z.looseObject({",
+            '  milestoneId: z.string().default("milestone"),',
+            "  passed: z.boolean().default(true),",
+            '  summary: z.string().default("Validation completed."),',
+            "  checks: z.array(z.object({",
+            "    name: z.string(),",
+            '    status: z.enum(["passed", "failed", "skipped"]),',
+            "    details: z.string().nullable().default(null),",
+            "  })).default([]),",
+            "  regressions: z.array(z.string()).default([]),",
+            "  followUps: z.array(z.string()).default([]),",
+            "});",
+            "",
+            "const missionFinalSchema = z.looseObject({",
+            '  status: z.enum(["completed", "partial", "cancelled"]).default("completed"),',
+            '  summary: z.string().default("Mission complete."),',
+            "  completedMilestones: z.number().int().default(0),",
+            "  totalMilestones: z.number().int().default(0),",
+            "  validationPassed: z.boolean().default(true),",
+            "  remainingRisks: z.array(z.string()).default([]),",
+            "  nextActions: z.array(z.string()).default([]),",
+            "  markdownBody: z.string().default(\"\"),",
+            "});",
+            "",
+            "const inputSchema = z.object({",
+            '  prompt: z.string().default("Describe the mission goal."),',
+            "  requirePlanApproval: z.boolean().default(true),",
+            "  maxMilestones: z.number().int().min(1).max(20).default(6),",
+            "  maxFeaturesPerMilestone: z.number().int().min(1).max(20).default(6),",
+            "  maxConcurrency: z.number().int().min(1).max(10).default(3),",
+            "  useWorktrees: z.boolean().default(false),",
+            '  baseBranch: z.string().default("main"),',
+            "});",
+            "",
+            "const { Workflow, Task, Sequence, Parallel, Approval, Worktree, smithers, outputs } = createSmithers({",
+            "  input: inputSchema,",
+            "  missionPlan: missionPlanSchema,",
+            "  missionApproval: missionApprovalSchema,",
+            "  missionFeature: missionFeatureResultSchema,",
+            "  milestoneIntegration: milestoneIntegrationSchema,",
+            "  milestoneValidation: milestoneValidationSchema,",
+            "  missionFinal: missionFinalSchema,",
+            "});",
+            "",
+            'const missionMemory = { kind: "workflow", id: "mission" } as const;',
+            "",
+            "function slugify(value: unknown, fallback: string): string {",
+            '  const normalized = String(value ?? "")',
+            "    .toLowerCase()",
+            '    .replace(/[^a-z0-9]+/g, "-")',
+            '    .replace(/^-+|-+$/g, "");',
+            "  return normalized.length > 0 ? normalized : fallback;",
+            "}",
+            "",
+            "function asStringArray(value: unknown): string[] {",
+            "  return Array.isArray(value) ? value.map((entry) => String(entry)).filter(Boolean) : [];",
+            "}",
+            "",
+            "function normalizeFeature(feature: any, index: number): any {",
+            "  const title = typeof feature?.title === \"string\" && feature.title.length > 0",
+            "    ? feature.title",
+            "    : `Feature ${index + 1}`;",
+            "  return {",
+            "    id: slugify(feature?.id ?? title, `feature-${index + 1}`),",
+            "    title,",
+            "    instructions: typeof feature?.instructions === \"string\" && feature.instructions.length > 0",
+            "      ? feature.instructions",
+            "      : `Complete ${title}.`,",
+            "    files: asStringArray(feature?.files),",
+            "    validation: asStringArray(feature?.validation),",
+            "    workerType: [\"implementation\", \"test\", \"docs\", \"research\"].includes(feature?.workerType)",
+            "      ? feature.workerType",
+            '      : "implementation",',
+            "    canRunInParallel: feature?.canRunInParallel !== false,",
+            "  };",
+            "}",
+            "",
+            "function normalizeMilestones(plan: any, maxMilestones: number, maxFeaturesPerMilestone: number): any[] {",
+            "  return (Array.isArray(plan?.milestones) ? plan.milestones : [])",
+            "    .slice(0, maxMilestones)",
+            "    .map((milestone: any, index: number) => {",
+            "      const title = typeof milestone?.title === \"string\" && milestone.title.length > 0",
+            "        ? milestone.title",
+            "        : `Milestone ${index + 1}`;",
+            "      const features = (Array.isArray(milestone?.features) ? milestone.features : [])",
+            "        .slice(0, maxFeaturesPerMilestone)",
+            "        .map((feature: any, featureIndex: number) => normalizeFeature(feature, featureIndex));",
+            "      return {",
+            "        id: slugify(milestone?.id ?? title, `milestone-${index + 1}`),",
+            "        title,",
+            "        objective: typeof milestone?.objective === \"string\" && milestone.objective.length > 0",
+            "          ? milestone.objective",
+            "          : title,",
+            "        validationPlan: asStringArray(milestone?.validationPlan),",
+            "        features: features.length > 0",
+            "          ? features",
+            "          : [normalizeFeature({ title, instructions: milestone?.objective ?? title }, 0)],",
+            "      };",
+            "    });",
+            "}",
+            "",
+            "function featureTaskId(milestoneIndex: number, feature: any): string {",
+            "  return `mission:milestone:${milestoneIndex + 1}:feature:${feature.id}`;",
+            "}",
+            "",
+            "function milestoneIntegrateId(milestoneIndex: number): string {",
+            "  return `mission:milestone:${milestoneIndex + 1}:integrate`;",
+            "}",
+            "",
+            "function milestoneValidationId(milestoneIndex: number): string {",
+            "  return `mission:milestone:${milestoneIndex + 1}:validate`;",
+            "}",
+            "",
+            "function milestoneFollowUpId(milestoneIndex: number): string {",
+            "  return `mission:milestone:${milestoneIndex + 1}:follow-up`;",
+            "}",
+            "",
+            "function milestoneRevalidationId(milestoneIndex: number): string {",
+            "  return `mission:milestone:${milestoneIndex + 1}:revalidate`;",
+            "}",
+            "",
+            "function featureNeeds(milestoneIndex: number, features: any[]): Record<string, string> {",
+            "  return Object.fromEntries(features.map((feature, index) => [`feature${index}`, featureTaskId(milestoneIndex, feature)]));",
+            "}",
+            "",
+            "function featureDeps(features: any[]): Record<string, typeof missionFeatureResultSchema> {",
+            "  return Object.fromEntries(features.map((_, index) => [`feature${index}`, outputs.missionFeature]));",
+            "}",
+            "",
+            "function workerAgentsFor(feature: any): any {",
+            "  if (feature.workerType === \"research\") return agents.smartTool;",
+            "  if (feature.workerType === \"docs\") return agents.cheapFast;",
+            "  return agents.smart;",
+            "}",
+            "",
+            "function previousMilestoneSummary(ctx: any): string {",
+            "  const integrations = ctx.outputs.milestoneIntegration ?? [];",
+            "  const validations = ctx.outputs.milestoneValidation ?? [];",
+            "  return [",
+            "    ...integrations.map((entry: any) => `Integration: ${entry.summary}`),",
+            "    ...validations.map((entry: any) => `Validation: ${entry.passed ? \"passed\" : \"failed\"} - ${entry.summary}`),",
+            "  ].slice(-8).join(\"\\n\");",
+            "}",
+            "",
+            "function milestoneIsTerminal(ctx: any, milestoneIndex: number): boolean {",
+            "  const revalidation = ctx.outputMaybe(\"milestoneValidation\", { nodeId: milestoneRevalidationId(milestoneIndex) });",
+            "  if (revalidation) return true;",
+            "  const validation = ctx.outputMaybe(\"milestoneValidation\", { nodeId: milestoneValidationId(milestoneIndex) });",
+            "  return Boolean(validation && validation.passed !== false);",
+            "}",
+            "",
+            "function activeMilestoneIndex(ctx: any, milestones: any[]): number {",
+            "  for (let index = 0; index < milestones.length; index += 1) {",
+            "    if (!milestoneIsTerminal(ctx, index)) return index;",
+            "  }",
+            "  return milestones.length;",
+            "}",
+            "",
+            "function renderFeatureWorker(ctx: any, plan: any, milestone: any, milestoneIndex: number, feature: any) {",
+            "  const taskId = featureTaskId(milestoneIndex, feature);",
+            "  const workerTask = (",
+            "    <Task",
+            "      key={taskId}",
+            "      id={taskId}",
+            "      output={outputs.missionFeature}",
+            "      agent={workerAgentsFor(feature)}",
+            "      timeoutMs={3_600_000}",
+            "      heartbeatTimeoutMs={900_000}",
+            "      continueOnFail",
+            "      memory={{",
+            "        recall: { namespace: missionMemory, query: `${plan.goal} ${milestone.title} ${feature.title}`, topK: 5 },",
+            "        remember: { namespace: missionMemory, key: taskId },",
+            "      }}",
+            "    >",
+            "      <MissionWorkerPrompt",
+            "        missionGoal={plan.goal || ctx.input.prompt}",
+            "        milestone={milestone}",
+            "        feature={feature}",
+            "        previousSummary={previousMilestoneSummary(ctx)}",
+            "      />",
+            "    </Task>",
+            "  );",
+            "",
+            "  if (!(ctx.input.useWorktrees ?? false)) return workerTask;",
+            "",
+            "  return (",
+            "    <Worktree",
+            "      key={taskId}",
+            "      id={`mission-worktree-${milestoneIndex + 1}-${feature.id}`}",
+            "      path={`.worktrees/mission-${milestoneIndex + 1}-${feature.id}`}",
+            "      branch={`mission/${milestoneIndex + 1}/${feature.id}`}",
+            "      baseBranch={ctx.input.baseBranch ?? \"main\"}",
+            "    >",
+            "      {workerTask}",
+            "    </Worktree>",
+            "  );",
+            "}",
+            "",
+            "function renderMilestone(ctx: any, plan: any, milestone: any, milestoneIndex: number) {",
+            "  const features = milestone.features;",
+            "  const integrationId = milestoneIntegrateId(milestoneIndex);",
+            "  const validationId = milestoneValidationId(milestoneIndex);",
+            "  const integration = ctx.outputMaybe(\"milestoneIntegration\", { nodeId: integrationId });",
+            "  const validation = ctx.outputMaybe(\"milestoneValidation\", { nodeId: validationId });",
+            "  const needsFollowUp = Boolean(validation && validation.passed === false);",
+            "",
+            "  return (",
+            "    <Sequence>",
+            "      <Parallel maxConcurrency={Math.min(ctx.input.maxConcurrency ?? 3, features.length)}>",
+            "        {features.map((feature: any) => renderFeatureWorker(ctx, plan, milestone, milestoneIndex, feature))}",
+            "      </Parallel>",
+            "      <Task",
+            "        id={integrationId}",
+            "        output={outputs.milestoneIntegration}",
+            "        agent={agents.smartTool}",
+            "        needs={featureNeeds(milestoneIndex, features)}",
+            "        deps={featureDeps(features)}",
+            "        timeoutMs={1_800_000}",
+            "        memory={{ remember: { namespace: missionMemory, key: integrationId } }}",
+            "      >",
+            "        {(deps: any) => {",
+            "          const results = features.map((_: any, index: number) => deps[`feature${index}`]);",
+            "          return (",
+            "            <MissionIntegratePrompt",
+            "              missionGoal={plan.goal || ctx.input.prompt}",
+            "              milestone={milestone}",
+            "              results={results}",
+            "              useWorktrees={ctx.input.useWorktrees ?? false}",
+            "            />",
+            "          );",
+            "        }}",
+            "      </Task>",
+            "      <Task",
+            "        id={validationId}",
+            "        output={outputs.milestoneValidation}",
+            "        agent={agents.smart}",
+            "        needs={{ integration: integrationId }}",
+            "        deps={{ integration: outputs.milestoneIntegration }}",
+            "        timeoutMs={1_800_000}",
+            "        heartbeatTimeoutMs={900_000}",
+            "        memory={{ remember: { namespace: missionMemory, key: validationId } }}",
+            "      >",
+            "        {(deps: any) => (",
+            "          <MissionValidatePrompt",
+            "            missionGoal={plan.goal || ctx.input.prompt}",
+            "            milestone={milestone}",
+            "            integration={deps.integration}",
+            "          />",
+            "        )}",
+            "      </Task>",
+            "      {needsFollowUp && (",
+            "        <Sequence>",
+            "          <Task",
+            "            id={milestoneFollowUpId(milestoneIndex)}",
+            "            output={outputs.missionFeature}",
+            "            agent={agents.smart}",
+            "            needs={{ validation: validationId }}",
+            "            deps={{ validation: outputs.milestoneValidation }}",
+            "            timeoutMs={1_800_000}",
+            "            memory={{ remember: { namespace: missionMemory, key: milestoneFollowUpId(milestoneIndex) } }}",
+            "          >",
+            "            {(deps: any) => (",
+            "              <MissionFollowUpPrompt",
+            "                missionGoal={plan.goal || ctx.input.prompt}",
+            "                milestone={milestone}",
+            "                validation={deps.validation}",
+            "              />",
+            "            )}",
+            "          </Task>",
+            "          <Task",
+            "            id={milestoneRevalidationId(milestoneIndex)}",
+            "            output={outputs.milestoneValidation}",
+            "            agent={agents.smart}",
+            "            needs={{ followUp: milestoneFollowUpId(milestoneIndex) }}",
+            "            deps={{ followUp: outputs.missionFeature }}",
+            "            timeoutMs={1_800_000}",
+            "            heartbeatTimeoutMs={900_000}",
+            "            memory={{ remember: { namespace: missionMemory, key: milestoneRevalidationId(milestoneIndex) } }}",
+            "          >",
+            "            {(deps: any) => (",
+            "              <MissionValidatePrompt",
+            "                missionGoal={plan.goal || ctx.input.prompt}",
+            "                milestone={milestone}",
+            "                integration={integration}",
+            "                followUp={deps.followUp}",
+            "              />",
+            "            )}",
+            "          </Task>",
+            "        </Sequence>",
+            "      )}",
+            "    </Sequence>",
+            "  );",
+            "}",
+            "",
+            "function renderFinal(ctx: any, plan: any, milestones: any[]) {",
+            "  return (",
+            "    <Task id=\"mission:final\" output={outputs.missionFinal} agent={agents.smartTool}>",
+            "      <MissionFinalPrompt",
+            "        plan={{ ...plan, milestones }}",
+            "        featureResults={ctx.outputs.missionFeature ?? []}",
+            "        integrationResults={ctx.outputs.milestoneIntegration ?? []}",
+            "        validationResults={ctx.outputs.milestoneValidation ?? []}",
+            "      />",
+            "    </Task>",
+            "  );",
+            "}",
+            "",
+            "export default smithers((ctx) => {",
+            "  const plan = ctx.outputMaybe(\"missionPlan\", { nodeId: \"mission:plan\" });",
+            "  const approval = ctx.outputMaybe(\"missionApproval\", { nodeId: \"mission:approve-plan\" });",
+            "  const approvalRequired = ctx.input.requirePlanApproval;",
+            "  const approvalDenied = approvalRequired && approval && approval.approved === false;",
+            "  const approved = !approvalRequired || approval?.approved === true;",
+            "  const milestones = normalizeMilestones(plan, ctx.input.maxMilestones ?? 6, ctx.input.maxFeaturesPerMilestone ?? 6);",
+            "  const activeIndex = approved ? activeMilestoneIndex(ctx, milestones) : 0;",
+            "",
+            "  return (",
+            "    <Workflow name=\"mission\">",
+            "      <Sequence>",
+            "        <Task",
+            "          id=\"mission:plan\"",
+            "          output={outputs.missionPlan}",
+            "          agent={agents.smartTool}",
+            "          timeoutMs={1_800_000}",
+            "          heartbeatTimeoutMs={900_000}",
+            "          memory={{ remember: { namespace: missionMemory, key: \"mission:plan\" } }}",
+            "        >",
+            "          <AskUserInstructions />",
+            "          <MissionPlanPrompt",
+            "            prompt={ctx.input.prompt}",
+            "            maxMilestones={ctx.input.maxMilestones ?? 6}",
+            "            maxFeaturesPerMilestone={ctx.input.maxFeaturesPerMilestone ?? 6}",
+            "          />",
+            "        </Task>",
+            "",
+            "        {plan && approvalRequired && !approval && (",
+            "          <Approval",
+            "            id=\"mission:approve-plan\"",
+            "            output={outputs.missionApproval}",
+            "            request={{",
+            "              title: \"Approve mission plan?\",",
+            "              summary: plan.summary || \"Review the scoped mission plan before workers begin.\",",
+            "              metadata: { milestones: milestones.length, risks: plan.risks ?? [] },",
+            "            }}",
+            "            onDeny=\"continue\"",
+            "          />",
+            "        )}",
+            "",
+            "        {approvalDenied && (",
+            "          <Task id=\"mission:cancelled\" output={outputs.missionFinal}>",
+            "            {{",
+            "              status: \"cancelled\",",
+            "              summary: `Mission plan was not approved. ${approval?.note ?? \"\"}`.trim(),",
+            "              completedMilestones: 0,",
+            "              totalMilestones: milestones.length,",
+            "              validationPassed: false,",
+            "              remainingRisks: plan?.risks ?? [],",
+            "              nextActions: [\"Revise the mission scope and rerun the workflow.\"],",
+            "              markdownBody: \"# Mission Cancelled\\n\\nThe plan was not approved.\",",
+            "            }}",
+            "          </Task>",
+            "        )}",
+            "",
+            "        {plan && approved && activeIndex < milestones.length && renderMilestone(ctx, plan, milestones[activeIndex], activeIndex)}",
+            "        {plan && approved && activeIndex >= milestones.length && renderFinal(ctx, plan, milestones)}",
+            "      </Sequence>",
+            "    </Workflow>",
+            "  );",
+            "});",
+        ]),
         {
             path: ".smithers/workflows/kanban.tsx",
             contents: [
@@ -2046,6 +2775,21 @@ function renderTemplateFiles(versions, env) {
             path: ".smithers/tsconfig.json",
             contents: renderTsconfig(),
         },
+        {
+            path: ".smithers/types/assets.d.ts",
+            contents: [
+                'declare module "*.md" {',
+                "  const Component: any;",
+                "  export default Component;",
+                "}",
+                "",
+                'declare module "*.mdx" {',
+                "  const Component: any;",
+                "  export default Component;",
+                "}",
+                "",
+            ].join("\n"),
+        },
         {
             path: ".smithers/bunfig.toml",
             contents: ['preload = ["./preload.ts"]', ""].join("\n"),
@@ -2054,6 +2798,7 @@ function renderTemplateFiles(versions, env) {
             path: ".smithers/preload.ts",
             contents: ['import { mdxPlugin } from "smithers-orchestrator";', "", "mdxPlugin();", ""].join("\n"),
         },
+        ...renderAgentScaffoldFiles(),
         {
             path: ".smithers/agents.ts",
             contents: generateAgentsTs(env),
@@ -2085,35 +2830,50 @@ function renderTemplateFiles(versions, env) {
  * @returns {InitResult}
  */
 export function initWorkflowPack(options = {}) {
-    const rootDir = resolve(options.rootDir ?? process.cwd(), ".smithers");
+    const projectRoot = options.rootDir ?? process.cwd();
+    const rootDir = resolve(projectRoot, ".smithers");
     const writtenFiles = [];
     const skippedFiles = [];
     const preservedPaths = [];
-    const versions = readDependencyVersions();
-    const env = process.env;
     ensureDir(rootDir);
-    ensureDir(resolve(rootDir, "prompts"));
-    ensureDir(resolve(rootDir, "components"));
-    ensureDir(resolve(rootDir, "workflows"));
-    ensureDir(resolve(rootDir, "tickets"));
-    const executionsDir = resolve(rootDir, "executions");
-    if (existsSync(executionsDir)) {
-        preservedPaths.push(executionsDir);
+    ensureDir(resolve(rootDir, "agents"));
+    /** @type {TemplateFile[]} */
+    let templateFiles;
+    if (options.agentsOnly) {
+        templateFiles = renderAgentScaffoldFiles();
     }
     else {
-        ensureDir(executionsDir);
+        const versions = readDependencyVersions();
+        const env = process.env;
+        ensureDir(resolve(rootDir, "prompts"));
+        ensureDir(resolve(rootDir, "components"));
+        ensureDir(resolve(rootDir, "workflows"));
+        ensureDir(resolve(rootDir, "tickets"));
+        const executionsDir = resolve(rootDir, "executions");
+        if (existsSync(executionsDir)) {
+            preservedPaths.push(executionsDir);
+        }
+        else {
+            ensureDir(executionsDir);
+        }
+        templateFiles = renderTemplateFiles(versions, env);
     }
-    for (const file of renderTemplateFiles(versions, env)) {
-        const absolutePath = resolve(options.rootDir ?? process.cwd(), file.path);
+    for (const file of templateFiles) {
+        const absolutePath = resolve(projectRoot, file.path);
         ensureParent(absolutePath);
-        if (existsSync(absolutePath) && !options.force) {
+        if (existsSync(absolutePath) && (file.preserveExisting || !options.force)) {
             skippedFiles.push(absolutePath);
+            if (file.preserveExisting) {
+                process.stderr.write(`[smithers:init] ${file.path} skipped: already exists\n`);
+            }
             continue;
         }
         writeFileSync(absolutePath, file.contents, "utf8");
         writtenFiles.push(absolutePath);
     }
-    const install = runBunInstall(rootDir, options.skipInstall ?? false);
+    const install = options.agentsOnly
+        ? { status: "skipped", reason: "agents-only" }
+        : runBunInstall(rootDir, options.skipInstall ?? false);
     return {
         rootDir,
         writtenFiles,
@@ -2156,8 +2916,10 @@ const WORKFLOW_FOLLOW_UPS = {
     "research": [
         { command: "workflow run write-a-prd", description: "Formalize findings into a PRD" },
         { command: "workflow run plan", description: "Turn research into an implementation plan" },
+        { command: "workflow run mission", description: "Run a scoped long-horizon mission" },
     ],
     "plan": [
+        { command: "workflow run mission", description: "Execute as a milestone-gated mission" },
         { command: "workflow run research-plan-implement", description: "Research, plan, and execute" },
         { command: "workflow run implement", description: "Execute the plan" },
         { command: "workflow run tickets-create", description: "Break plan into tickets" },
@@ -2180,6 +2942,7 @@ const WORKFLOW_FOLLOW_UPS = {
         { command: "workflow run tickets-create", description: "Break directly into tickets" },
     ],
     "write-a-prd": [
+        { command: "workflow run mission", description: "Execute the PRD as a mission" },
         { command: "workflow run tickets-create", description: "Break PRD into implementable tickets" },
         { command: "workflow run plan", description: "Turn PRD into a phased plan" },
         { command: "workflow run implement", description: "Start building from the PRD" },
@@ -2196,6 +2959,11 @@ const WORKFLOW_FOLLOW_UPS = {
         { command: "workflow run review", description: "Review the changes" },
         { command: "workflow run improve-test-coverage", description: "Improve test coverage" },
     ],
+    "mission": [
+        { command: "workflow run review", description: "Review mission changes" },
+        { command: "workflow run improve-test-coverage", description: "Fill validation gaps" },
+        { command: "workflow run audit", description: "Audit completed feature areas" },
+    ],
     "review": [
         { command: "workflow run implement", description: "Address review feedback" },
     ],