@neriros/ralphy 3.10.8 → 3.10.10

package/dist/shell/index.js

@@ -18928,8 +18928,8 @@ import { readFileSync } from "fs";
 import { resolve } from "path";
 function getVersion() {
   try {
-    if ("3.10.8")
-      return "3.10.8";
+    if ("3.10.10")
+      return "3.10.10";
   } catch {}
   const dirsToTry = [];
   try {
@@ -19376,6 +19376,764 @@ var init_src2 = __esm(() => {
   noopFallback = createNoopBus();
 });
 
+// packages/workflow/src/fields.ts
+function fieldsForMode(mode, answers = {}, restrictTo) {
+  const all = mode === "customized" ? CUSTOMIZED_FIELDS : QUICK_FIELDS;
+  const allowed = restrictTo ? new Set(restrictTo) : null;
+  return all.filter((field) => {
+    if (HIDDEN_FIELD_IDS.has(field.id))
+      return false;
+    if (allowed && !allowed.has(field.id))
+      return false;
+    return !field.when || field.when(answers);
+  });
+}
+function findField(id) {
+  return CUSTOMIZED_FIELDS.find((field) => field.id === id);
+}
+function modelOptionValues() {
+  const field = findField("model");
+  return field && field.spec.kind === "select" ? field.spec.options.map((o) => o.value) : [];
+}
+var PROMPT_BODY_FIELD_ID = "promptBody", REPO_LINK_FIELD_ID = "repo.link", yes = () => ({ kind: "confirm", defaultChoice: "confirm" }), no = () => ({ kind: "confirm", defaultChoice: "cancel" }), PROJECT_NAME, LINEAR_TEAM, REPO_LINK, LINEAR_ASSIGNEE_CHOICE_FIELD_ID = "linear.assigneeChoice", LINEAR_ASSIGNEE_VALUE_FIELD_ID = "linear.assigneeValue", LINEAR_FILTER_DESCRIPTION, LINEAR_ASSIGNEE_CHOICE, LINEAR_ASSIGNEE_VALUE, QUICK_FIELDS, isOn = (id) => (answers) => answers[id] === true, concurrencyForcesWorktree = (answers) => {
+  const value = answers["concurrency"];
+  return typeof value === "number" && value > 1;
+}, worktreeEnabled = (answers) => answers["useWorktree"] === true || concurrencyForcesWorktree(answers), HIDDEN_FIELD_IDS, CUSTOMIZED_FIELDS, COMMON_CLI_OPTIONS, FIELD_DESCRIPTIONS;
+var init_fields = __esm(() => {
+  PROJECT_NAME = {
+    id: "project.name",
+    label: "Project name",
+    description: "The project's display name. Ralphy puts it in the agent's prompt and in its logs.",
+    spec: { kind: "text", placeholder: "my-project" }
+  };
+  LINEAR_TEAM = {
+    id: "linear.team",
+    label: "Linear team key",
+    hint: "e.g. ENG \u2014 leave blank to match all teams",
+    description: "The Linear team this repository is linked to, given by its key (e.g. ENG). Ralphy only picks up issues from this team. Leave blank to watch every team.",
+    emptyLabel: "all teams",
+    spec: { kind: "text" }
+  };
+  REPO_LINK = {
+    id: "repo.link",
+    label: "Record this repository in WORKFLOW.md?",
+    description: "Record the detected git repository in WORKFLOW.md so Ralphy maps this project's Linear issues to it. Confirm to adopt the detected repo; decline to leave it out.",
+    spec: yes(),
+    when: (answers) => typeof answers["repo.name"] === "string" && answers["repo.name"] !== ""
+  };
+  LINEAR_FILTER_DESCRIPTION = "Global filter applied to every Linear ticket fetch, as an 'assignee = <value>' clause. " + "<value> is 'me' (issues assigned to you), 'any' (regardless of assignee), 'unassigned', " + "or a specific Linear user (email or user-id). Blank defaults to 'assignee = me'.";
+  LINEAR_ASSIGNEE_CHOICE = {
+    id: LINEAR_ASSIGNEE_CHOICE_FIELD_ID,
+    label: "Linear assignee filter",
+    description: "Which Linear issues Ralphy fetches, by assignee: 'me' (assigned to you), 'any' (regardless of assignee), 'unassigned', or a specific user you name next.",
+    spec: {
+      kind: "select",
+      options: [
+        { label: "me (assigned to you)", value: "me" },
+        { label: "any (regardless of assignee)", value: "any" },
+        { label: "unassigned", value: "unassigned" },
+        { label: "a specific user (email or user-id)\u2026", value: "other" }
+      ]
+    }
+  };
+  LINEAR_ASSIGNEE_VALUE = {
+    id: LINEAR_ASSIGNEE_VALUE_FIELD_ID,
+    label: "Assignee email or user-id",
+    description: "The specific Linear user to filter by \u2014 their email address or Linear user-id.",
+    spec: { kind: "text", placeholder: "you@example.com" },
+    when: (answers) => answers[LINEAR_ASSIGNEE_CHOICE_FIELD_ID] === "other"
+  };
+  QUICK_FIELDS = [
+    PROJECT_NAME,
+    LINEAR_TEAM,
+    REPO_LINK,
+    LINEAR_ASSIGNEE_CHOICE,
+    LINEAR_ASSIGNEE_VALUE
+  ];
+  HIDDEN_FIELD_IDS = new Set([
+    "appendPrompt",
+    "metaPrompt.enabled",
+    "metaPrompt.effort",
+    "logRawStream",
+    "maxConsecutiveFailuresPerTask",
+    "prDraft",
+    "manualMergeWhenAutoMergeDisabled",
+    "finalizeNoOpAsDone",
+    "linear.confirmationMode.maxConfirmationRounds",
+    "openspec.reviewPhase.enabled"
+  ]);
+  CUSTOMIZED_FIELDS = [
+    PROJECT_NAME,
+    {
+      id: "project.language",
+      label: "Language",
+      description: "Primary programming language (e.g. TypeScript). Added to the agent's prompt as context.",
+      spec: { kind: "text", placeholder: "TypeScript" }
+    },
+    {
+      id: "project.framework",
+      label: "Framework",
+      description: "Primary framework or toolchain (e.g. Bun + Nx). Added to the agent's prompt as context.",
+      spec: { kind: "text", placeholder: "Bun + Nx" }
+    },
+    {
+      id: "commands.test",
+      label: "Test command",
+      description: "Shell command Ralphy runs to check the agent's work each iteration; its exit code decides pass or fail.",
+      spec: { kind: "text", placeholder: "bun test" }
+    },
+    {
+      id: "commands.lint",
+      label: "Lint command",
+      description: "Shell command Ralphy runs to lint the code before a task is allowed to finish.",
+      spec: { kind: "text", placeholder: "bun run lint" }
+    },
+    {
+      id: "commands.build",
+      label: "Build command",
+      description: "Shell command Ralphy runs to confirm the project still compiles / builds.",
+      spec: { kind: "text", placeholder: "bun run build" }
+    },
+    {
+      id: "commands.typecheck",
+      label: "Typecheck command",
+      description: "Shell command Ralphy runs to confirm the project's types still pass.",
+      spec: { kind: "text", placeholder: "bun run typecheck" }
+    },
+    {
+      id: "engine",
+      label: "Engine",
+      description: "Which AI coding tool runs the loop: 'claude' (Claude Code) or 'codex' (OpenAI Codex).",
+      spec: {
+        kind: "select",
+        options: [
+          { label: "claude", value: "claude" },
+          { label: "codex", value: "codex" }
+        ]
+      }
+    },
+    {
+      id: "model",
+      label: "Model tier",
+      description: "Model tier the engine uses. 'opus' is the most capable, 'haiku' the cheapest and fastest; higher tiers cost more per token.",
+      spec: {
+        kind: "select",
+        options: [
+          { label: "opus", value: "opus" },
+          { label: "sonnet", value: "sonnet" },
+          { label: "haiku", value: "haiku" }
+        ]
+      }
+    },
+    {
+      id: "logRawStream",
+      label: "Log the raw engine stream to stdout?",
+      description: "Print the engine's raw event stream to the terminal. Very verbose \u2014 mainly for debugging.",
+      spec: no()
+    },
+    {
+      id: "taskVerbose",
+      label: "Show detailed task output?",
+      description: "Show detailed per-task output (passes --verbose to the task sub-process) for extra diagnostics.",
+      spec: no()
+    },
+    {
+      id: "concurrency",
+      label: "Concurrency (parallel tasks)",
+      description: "How many tasks Ralphy works on at once. Higher finishes faster but uses more API quota simultaneously.",
+      spec: { kind: "number", placeholder: "1" }
+    },
+    {
+      id: "pollIntervalSeconds",
+      label: "Poll interval (seconds)",
+      description: "In agent mode, how often (in seconds) Ralphy checks Linear for new issues to pick up.",
+      spec: { kind: "number", placeholder: "60" }
+    },
+    {
+      id: "iterationDelaySeconds",
+      label: "Delay between iterations (seconds)",
+      description: "Seconds to pause between loop iterations \u2014 a throttle to slow spend. 0 means no pause.",
+      spec: { kind: "number", placeholder: "0" }
+    },
+    {
+      id: "maxIterationsPerTask",
+      label: "Max iterations per task (0 = unlimited)",
+      description: "Stop a task after this many loop iterations. 0 means no limit (run until done or another limit hits).",
+      spec: { kind: "number", placeholder: "0" }
+    },
+    {
+      id: "maxCostUsdPerTask",
+      label: "Max cost USD per task (0 = unlimited)",
+      description: "Stop a task once its API spend passes this many US dollars. 0 means no cost limit.",
+      spec: { kind: "number", placeholder: "0" }
+    },
+    {
+      id: "maxRuntimeMinutesPerTask",
+      label: "Max runtime minutes per task (0 = unlimited)",
+      description: "Stop a task after this many minutes of wall-clock time. 0 means no time limit.",
+      spec: { kind: "number", placeholder: "0" }
+    },
+    {
+      id: "maxConsecutiveFailuresPerTask",
+      label: "Max consecutive identical failures",
+      description: "Give up on a task after this many identical failures in a row \u2014 a guard against stuck loops.",
+      spec: { kind: "number", placeholder: "5" }
+    },
+    {
+      id: "useWorktree",
+      label: "Run each task in an isolated git worktree?",
+      description: "Run each task in its own git worktree (a separate working copy of the repo) so parallel tasks don't overwrite each other's files. Forced on when concurrency is greater than 1.",
+      spec: no(),
+      when: (answers) => !concurrencyForcesWorktree(answers)
+    },
+    {
+      id: "cleanupWorktreeOnSuccess",
+      label: "Delete the worktree after a successful task?",
+      description: "Delete a task's worktree (its separate working copy) once it succeeds, to reclaim disk space.",
+      spec: no(),
+      when: worktreeEnabled
+    },
+    {
+      id: "setupScript",
+      label: "Worktree setup script (runs before each task)",
+      description: "Part of the worktree flow: a shell script run once in each task's fresh worktree before the task starts \u2014 e.g. to install dependencies in the new working copy.",
+      spec: { kind: "text" },
+      when: worktreeEnabled
+    },
+    {
+      id: "teardownScript",
+      label: "Worktree teardown script (runs after each task)",
+      description: "Part of the worktree flow: a shell script run once in each task's worktree after the task ends \u2014 e.g. to clean up before the worktree is removed.",
+      spec: { kind: "text" },
+      when: worktreeEnabled
+    },
+    {
+      id: "enableManualTest",
+      label: "Enable the manual-test phase?",
+      description: "Add a phase that pauses for a human to manually test the change (e.g. in the UI) before the task is marked done.",
+      spec: no()
+    },
+    {
+      id: "appendPrompt",
+      label: "Extra text appended to every prompt",
+      description: "Free text added to the end of every prompt sent to the agent \u2014 house rules or reminders.",
+      spec: { kind: "text" }
+    },
+    {
+      id: "createPrOnSuccess",
+      label: "Open a pull request when a task succeeds?",
+      description: "When a task succeeds, automatically push the branch and open a GitHub pull request (PR).",
+      spec: no()
+    },
+    {
+      id: "prDraft",
+      label: "Open pull requests as drafts?",
+      description: "Open PRs as drafts (marked not-ready-for-review) instead of ready for review.",
+      spec: no(),
+      when: isOn("createPrOnSuccess")
+    },
+    {
+      id: "prBaseBranch",
+      label: "PR base branch",
+      description: "The branch new pull requests merge into (their base) \u2014 e.g. main.",
+      spec: { kind: "text", placeholder: "main" },
+      when: isOn("createPrOnSuccess")
+    },
+    {
+      id: "stackPrsOnDependencies",
+      label: "Stack dependent issues' PRs onto their blocker's PR?",
+      description: "If an issue is blocked by another that already has an open PR, base this issue's PR on that PR's branch instead of main (a 'stacked' PR).",
+      spec: no(),
+      when: isOn("createPrOnSuccess")
+    },
+    {
+      id: "autoMergeStrategy",
+      label: "Auto-merge strategy",
+      description: "How GitHub combines the PR's commits when it auto-merges: squash (one commit), merge (a merge commit), or rebase.",
+      spec: {
+        kind: "select",
+        options: [
+          { label: "squash", value: "squash" },
+          { label: "merge", value: "merge" },
+          { label: "rebase", value: "rebase" }
+        ]
+      },
+      when: isOn("createPrOnSuccess")
+    },
+    {
+      id: "manualMergeWhenAutoMergeDisabled",
+      label: "Merge manually when GitHub auto-merge is disabled?",
+      description: "If the repo doesn't have GitHub's auto-merge feature enabled, have Ralphy merge the PR itself once checks pass.",
+      spec: yes(),
+      when: isOn("createPrOnSuccess")
+    },
+    {
+      id: "finalizeNoOpAsDone",
+      label: "Finalize a no-op (meta-only) change as done?",
+      description: "If a change ended up touching only meta files (specs, task lists) and no real code, mark the issue done instead of retrying it.",
+      spec: yes()
+    },
+    {
+      id: "fixCiOnFailure",
+      label: "Let the agent fix CI failures?",
+      description: "After opening a PR, watch its CI (the automated checks GitHub runs) and let the agent push fixes when they fail.",
+      spec: no()
+    },
+    {
+      id: "maxCiFixAttempts",
+      label: "Max CI-fix attempts per task",
+      description: "Stop trying to fix failing CI after this many attempts.",
+      spec: { kind: "number", placeholder: "5" },
+      when: isOn("fixCiOnFailure")
+    },
+    {
+      id: "ciPollIntervalSeconds",
+      label: "CI status poll interval (seconds)",
+      description: "How often (in seconds) to re-check the PR's CI status while waiting on or fixing it.",
+      spec: { kind: "number", placeholder: "30" },
+      when: isOn("fixCiOnFailure")
+    },
+    {
+      id: "ignoreCiChecks",
+      label: "CI checks to ignore",
+      description: "Names of CI checks to ignore when deciding whether a PR is green \u2014 e.g. known-flaky jobs.",
+      spec: { kind: "list", placeholder: "check name" }
+    },
+    {
+      id: "rules",
+      label: "Project rules",
+      description: "House rules added to every prompt (e.g. 'never edit generated files'). One rule per entry.",
+      spec: { kind: "list", placeholder: "a rule" }
+    },
+    {
+      id: "boundaries.never_touch",
+      label: "Never-touch globs",
+      description: "Glob patterns for files the agent must never modify (e.g. dist/**).",
+      spec: { kind: "list", placeholder: "dist/**" }
+    },
+    LINEAR_TEAM,
+    REPO_LINK,
+    LINEAR_ASSIGNEE_CHOICE,
+    LINEAR_ASSIGNEE_VALUE,
+    {
+      id: "linear.postComments",
+      label: "Post progress comments on the Linear issue?",
+      description: "Post progress comments on the Linear issue while a task runs.",
+      spec: yes()
+    },
+    {
+      id: "linear.updateEveryIterations",
+      label: "Post a progress update every N iterations (0 = off)",
+      description: "Post a progress comment every N loop iterations. 0 turns periodic updates off.",
+      spec: { kind: "number", placeholder: "10" }
+    },
+    {
+      id: "linear.mentionTrigger",
+      label: "Watch comments/PRs for @mentions?",
+      description: "Watch a finished issue's comments and its PR for @mentions of Ralphy, and re-engage when mentioned.",
+      spec: yes()
+    },
+    {
+      id: "linear.mentionHandle",
+      label: "Mention handle",
+      description: "The @handle that, when mentioned, makes Ralphy pick the issue back up (e.g. @ralphy).",
+      spec: { kind: "text", placeholder: "@ralphy" },
+      when: isOn("linear.mentionTrigger")
+    },
+    {
+      id: "linear.codeReviewTrigger",
+      label: "Watch PRs for unresolved review threads?",
+      description: "Watch open PRs for unresolved review comments and re-engage to address them.",
+      spec: yes()
+    },
+    {
+      id: "linear.codeReviewStaleHours",
+      label: "Code-review stale window (hours)",
+      description: "Ignore review comments older than this many hours, so stale threads don't re-trigger work.",
+      spec: { kind: "number", placeholder: "24" },
+      when: isOn("linear.codeReviewTrigger")
+    },
+    {
+      id: "linear.syncTasksToComment",
+      label: "Sync tasks into a sticky Linear comment?",
+      description: "Keep one pinned ('sticky') Linear comment in sync with the task checklist (tasks.md).",
+      spec: yes()
+    },
+    {
+      id: "linear.syncSpecsAsAttachments",
+      label: "Upload plan as attachments to the Linear ticket?",
+      description: "Upload the OpenSpec planning docs (proposal.md, design.md) to the issue as attachments. OpenSpec is Ralphy's spec-driven planning format.",
+      spec: yes()
+    },
+    {
+      id: "linear.specAttachmentFormats",
+      label: "Plan attachment formats",
+      description: "Which formats to upload the spec docs in: 'md' (raw markdown), 'pdf' (a rendered PDF), or both.",
+      spec: {
+        kind: "multiselect",
+        options: [
+          { label: "md", value: "md" },
+          { label: "pdf", value: "pdf" }
+        ]
+      },
+      when: isOn("linear.syncSpecsAsAttachments")
+    },
+    {
+      id: "linear.confirmationMode.enabled",
+      label: "Enable the human confirmation gate?",
+      description: "Pause after the agent finishes planning and wait for a human to approve before it writes any code (a confirmation gate).",
+      spec: no()
+    },
+    {
+      id: "linear.confirmationMode.timeoutHours",
+      label: "Confirmation timeout (hours)",
+      description: "If no one approves or rejects within this many hours, auto-resolve the confirmation gate.",
+      spec: { kind: "number", placeholder: "48" },
+      when: isOn("linear.confirmationMode.enabled")
+    },
+    {
+      id: "linear.confirmationMode.maxConfirmationRounds",
+      label: "Max confirmation rounds",
+      description: "How many times the plan can be revised and re-submitted for approval before Ralphy gives up.",
+      spec: { kind: "number", placeholder: "3" },
+      when: isOn("linear.confirmationMode.enabled")
+    },
+    {
+      id: "linear.indicators",
+      label: "Linear lifecycle indicators",
+      description: "How Ralphy maps lifecycle events to Linear statuses/labels \u2014 which issues to pick up (todo) and what to set when a task is in progress, done, or errored.",
+      spec: { kind: "indicators" }
+    },
+    {
+      id: "preExistingErrorCheck.enabled",
+      label: "Enable the base-branch health gate?",
+      description: "Before picking up new work, run health-check commands on the base branch and pause if it's already broken, so the agent isn't blamed for pre-existing failures.",
+      spec: no()
+    },
+    {
+      id: "preExistingErrorCheck.commands",
+      label: "Health-gate commands (blank = use lint/test)",
+      description: "Commands run against the base branch to judge its health. Leave empty to reuse your lint/test commands.",
+      spec: { kind: "list", placeholder: "bun run lint" },
+      when: isOn("preExistingErrorCheck.enabled")
+    },
+    {
+      id: "preExistingErrorCheck.baseBranch",
+      label: "Health-gate base branch",
+      description: "The branch the health gate checks out and tests (usually main).",
+      spec: { kind: "text", placeholder: "main" },
+      when: isOn("preExistingErrorCheck.enabled")
+    },
+    {
+      id: "preExistingErrorCheck.label",
+      label: "Health-gate Linear label",
+      description: "Linear label applied to the ticket Ralphy opens when the base branch is found broken.",
+      spec: { kind: "text", placeholder: "ralph:pre-existing-error" },
+      when: isOn("preExistingErrorCheck.enabled")
+    },
+    {
+      id: "prTracker.enabled",
+      label: "Enable the PR tracker?",
+      description: "Keep watching the PRs Ralphy opened and automatically try to recover any whose merge state goes red (conflicts or failing CI).",
+      spec: yes()
+    },
+    {
+      id: "prTracker.maxRecoveryAttempts",
+      label: "PR tracker max recovery attempts",
+      description: "Give up auto-recovering a red PR after this many attempts, then flag it for a human.",
+      spec: { kind: "number", placeholder: "3" },
+      when: isOn("prTracker.enabled")
+    },
+    {
+      id: "prTracker.advanceMergedToDone",
+      label: "Advance merged PRs to done automatically?",
+      description: "Move an issue to its done state as soon as its PR is merged.",
+      spec: no(),
+      when: isOn("prTracker.enabled")
+    },
+    {
+      id: "metaPrompt.enabled",
+      label: "Enable the meta-prompt addendum?",
+      description: "Add Ralphy's task-level 'meta-prompt' layer (extra framing instructions) to each phase. Leave on unless you want raw prompts.",
+      spec: yes()
+    },
+    {
+      id: "metaPrompt.effort",
+      label: "Per-ticket effort tier",
+      description: "How much effort the meta-prompt nudges the agent toward per ticket. 'auto' detects it from the ticket; 'light'/'standard'/'heavy' pin every ticket to that tier.",
+      spec: {
+        kind: "select",
+        options: [
+          { label: "auto", value: "auto" },
+          { label: "light", value: "light" },
+          { label: "standard", value: "standard" },
+          { label: "heavy", value: "heavy" }
+        ]
+      },
+      when: isOn("metaPrompt.enabled")
+    },
+    {
+      id: "openspec.reviewPhase.enabled",
+      label: "Enable the OpenSpec review phase?",
+      description: "After all tasks finish, spawn a separate reviewer agent that reads the full diff and writes review findings; open findings loop back into more work.",
+      spec: no()
+    },
+    {
+      id: "openspec.reviewPhase.maxRounds",
+      label: "Review phase max rounds",
+      description: "How many review\u2192fix cycles to run before the change is archived regardless.",
+      spec: { kind: "number", placeholder: "1" },
+      when: isOn("openspec.reviewPhase.enabled")
+    },
+    {
+      id: "openspec.reviewPhase.reviewerModel",
+      label: "Reviewer model (blank = same as main)",
+      description: "Model used for the review pass. Blank reuses the main model; a cheaper tier (e.g. haiku) saves cost.",
+      spec: { kind: "text", placeholder: "haiku" },
+      when: isOn("openspec.reviewPhase.enabled")
+    },
+    {
+      id: "openspec.reviewPhase.reviewerContextStrategy",
+      label: "Reviewer context",
+      description: "'fresh' gives the reviewer a brand-new session (unbiased); 'warm' resumes the last task's session (more context, cheaper).",
+      spec: {
+        kind: "select",
+        options: [
+          { label: "fresh", value: "fresh" },
+          { label: "warm", value: "warm" }
+        ]
+      },
+      when: isOn("openspec.reviewPhase.enabled")
+    },
+    {
+      id: PROMPT_BODY_FIELD_ID,
+      label: "Customize the prompt sent to the agent?",
+      description: "The prompt the agent receives lives in the file body \u2014 a template filled with per-issue values (e.g. {{ issue.identifier }}). Edit it here, or leave it and finish to keep the default.",
+      spec: { kind: "multiline" }
+    }
+  ];
+  COMMON_CLI_OPTIONS = [
+    { fieldId: "model", flag: "--model", argKey: "model", kind: "model" },
+    { fieldId: "iterationDelaySeconds", flag: "--delay", argKey: "delay", kind: "int" },
+    { fieldId: "maxCostUsdPerTask", flag: "--max-cost", argKey: "maxCostUsd", kind: "float" },
+    {
+      fieldId: "maxRuntimeMinutesPerTask",
+      flag: "--max-runtime",
+      argKey: "maxRuntimeMinutes",
+      kind: "float"
+    },
+    {
+      fieldId: "maxConsecutiveFailuresPerTask",
+      flag: "--max-failures",
+      argKey: "maxConsecutiveFailures",
+      kind: "int"
+    },
+    {
+      fieldId: "maxIterationsPerTask",
+      flag: "--max-iterations",
+      argKey: "maxIterations",
+      kind: "int"
+    },
+    { fieldId: "logRawStream", flag: "--log", argKey: "log", kind: "boolean" },
+    { fieldId: "taskVerbose", flag: "--verbose", argKey: "verbose", kind: "boolean" }
+  ];
+  FIELD_DESCRIPTIONS = [
+    ...CUSTOMIZED_FIELDS.filter((field) => Boolean(field.description) && field.spec.kind !== "multiline").map((field) => ({ path: field.id.split("."), description: field.description })),
+    { path: ["linear", "filter"], description: LINEAR_FILTER_DESCRIPTION }
+  ];
+});
+
+// packages/cli-args/src/common-args.ts
+import { resolve as resolve2 } from "path";
+function initialCommonArgs() {
+  return {
+    engine: "claude",
+    model: "opus",
+    engineSet: false,
+    maxIterations: 0,
+    maxCostUsd: 0,
+    maxRuntimeMinutes: 0,
+    maxConsecutiveFailures: 5,
+    delay: 0,
+    log: false,
+    verbose: false,
+    projectRoot: undefined,
+    workflowFile: undefined,
+    name: "",
+    prompt: "",
+    fromAgent: false
+  };
+}
+function applyValueOption(option, args, raw) {
+  const setter = VALUE_SETTERS[option.argKey];
+  if (!setter)
+    throw new Error("no value setter registered for CLI option");
+  setter(args, raw);
+}
+function applyBooleanOption(option, args) {
+  const setter = BOOLEAN_SETTERS[option.argKey];
+  if (!setter)
+    throw new Error("no boolean setter registered for CLI option");
+  setter(args);
+}
+function emptyParseState() {
+  return {
+    pendingOption: null,
+    expectClaudeModel: false,
+    expectProjectRoot: false,
+    expectWorkflow: false,
+    expectName: false,
+    expectPrompt: false,
+    expectPromptFile: false,
+    promptFilePath: null,
+    workflowFileRaw: null
+  };
+}
+function parseCommonArg(arg, args, state) {
+  if (state.pendingOption) {
+    applyValueOption(state.pendingOption, args, arg);
+    state.pendingOption = null;
+    return true;
+  }
+  if (state.expectClaudeModel) {
+    state.expectClaudeModel = false;
+    if (VALID_MODELS.has(arg)) {
+      args.model = arg;
+      return true;
+    }
+  }
+  if (state.expectProjectRoot) {
+    args.projectRoot = arg;
+    state.expectProjectRoot = false;
+    return true;
+  }
+  if (state.expectWorkflow) {
+    state.workflowFileRaw = arg;
+    args.workflowFile = resolve2(arg);
+    state.expectWorkflow = false;
+    return true;
+  }
+  if (state.expectName) {
+    args.name = arg;
+    state.expectName = false;
+    return true;
+  }
+  if (state.expectPrompt) {
+    args.prompt = arg;
+    state.promptFilePath = null;
+    state.expectPrompt = false;
+    return true;
+  }
+  if (state.expectPromptFile) {
+    state.promptFilePath = arg;
+    state.expectPromptFile = false;
+    return true;
+  }
+  const option = OPTION_BY_FLAG.get(arg);
+  if (option) {
+    if (option.kind === "boolean")
+      applyBooleanOption(option, args);
+    else
+      state.pendingOption = option;
+    return true;
+  }
+  switch (arg) {
+    case "--claude":
+      if (args.engineSet && args.engine !== "claude") {
+        throw new Error("Choose only one engine flag: --claude or --codex");
+      }
+      args.engine = "claude";
+      args.engineSet = true;
+      state.expectClaudeModel = true;
+      return true;
+    case "--codex":
+      if (args.engineSet && args.engine !== "codex") {
+        throw new Error("Choose only one engine flag: --claude or --codex");
+      }
+      args.engine = "codex";
+      args.engineSet = true;
+      return true;
+    case "--unlimited":
+      args.maxIterations = 0;
+      return true;
+    case "--project-root":
+      state.expectProjectRoot = true;
+      return true;
+    case "--workflow":
+      state.expectWorkflow = true;
+      return true;
+    case "--name":
+      state.expectName = true;
+      return true;
+    case "--prompt":
+      state.expectPrompt = true;
+      return true;
+    case "--prompt-file":
+      state.expectPromptFile = true;
+      return true;
+    case "--from-agent":
+      args.fromAgent = true;
+      return true;
+    default:
+      return false;
+  }
+}
+async function resolvePromptFile(args, state) {
+  if (state.promptFilePath !== null) {
+    args.prompt = await Bun.file(state.promptFilePath).text();
+  }
+}
+function resolveWorkflowFile(args, state) {
+  if (state.workflowFileRaw !== null && args.projectRoot !== undefined) {
+    args.workflowFile = resolve2(args.projectRoot, state.workflowFileRaw);
+  }
+}
+function parseWorkflowPathArgs(argv) {
+  const args = initialCommonArgs();
+  const state = emptyParseState();
+  for (const token of argv)
+    parseCommonArg(token, args, state);
+  resolveWorkflowFile(args, state);
+  return { projectRoot: args.projectRoot, workflowFile: args.workflowFile };
+}
+var VALID_MODELS, OPTION_BY_FLAG, VALUE_FLAGS, VALUE_SETTERS, BOOLEAN_SETTERS;
+var init_common_args = __esm(() => {
+  init_fields();
+  VALID_MODELS = new Set(modelOptionValues());
+  OPTION_BY_FLAG = new Map(COMMON_CLI_OPTIONS.map((option) => [option.flag, option]));
+  VALUE_FLAGS = new Set(COMMON_CLI_OPTIONS.filter((option) => option.kind !== "boolean").map((option) => option.flag));
+  VALUE_SETTERS = {
+    model: (args, raw) => {
+      if (!VALID_MODELS.has(raw))
+        throw new Error("Invalid model");
+      args.model = raw;
+    },
+    delay: (args, raw) => {
+      args.delay = parseInt(raw, 10);
+    },
+    maxCostUsd: (args, raw) => {
+      args.maxCostUsd = parseFloat(raw);
+    },
+    maxRuntimeMinutes: (args, raw) => {
+      args.maxRuntimeMinutes = parseFloat(raw);
+    },
+    maxConsecutiveFailures: (args, raw) => {
+      args.maxConsecutiveFailures = parseInt(raw, 10);
+    },
+    maxIterations: (args, raw) => {
+      args.maxIterations = parseInt(raw, 10);
+    }
+  };
+  BOOLEAN_SETTERS = {
+    log: (args) => {
+      args.log = true;
+    },
+    verbose: (args) => {
+      args.verbose = true;
+    }
+  };
+});
+
 // node_modules/.bun/react@18.3.1/node_modules/react/cjs/react.development.js
 var require_react_development = __commonJS((exports, module) => {
   if (true) {
@@ -21016,14 +21774,14 @@ Check the top-level render call using <` + parentName + ">.";
             var thenableResult = result;
             var wasAwaited = false;
             var thenable = {
-              then: function(resolve2, reject) {
+              then: function(resolve3, reject) {
                 wasAwaited = true;
                 thenableResult.then(function(returnValue2) {
                   popActScope(prevActScopeDepth);
                   if (actScopeDepth === 0) {
-                    recursivelyFlushAsyncActWork(returnValue2, resolve2, reject);
+                    recursivelyFlushAsyncActWork(returnValue2, resolve3, reject);
                   } else {
-                    resolve2(returnValue2);
+                    resolve3(returnValue2);
                   }
                 }, function(error2) {
                   popActScope(prevActScopeDepth);
@@ -21052,20 +21810,20 @@ Check the top-level render call using <` + parentName + ">.";
                 ReactCurrentActQueue.current = null;
               }
               var _thenable = {
-                then: function(resolve2, reject) {
+                then: function(resolve3, reject) {
                   if (ReactCurrentActQueue.current === null) {
                     ReactCurrentActQueue.current = [];
-                    recursivelyFlushAsyncActWork(returnValue, resolve2, reject);
+                    recursivelyFlushAsyncActWork(returnValue, resolve3, reject);
                   } else {
-                    resolve2(returnValue);
+                    resolve3(returnValue);
                   }
                 }
               };
               return _thenable;
             } else {
               var _thenable2 = {
-                then: function(resolve2, reject) {
-                  resolve2(returnValue);
+                then: function(resolve3, reject) {
+                  resolve3(returnValue);
                 }
               };
               return _thenable2;
@@ -21081,7 +21839,7 @@ Check the top-level render call using <` + parentName + ">.";
           actScopeDepth = prevActScopeDepth;
         }
       }
-      function recursivelyFlushAsyncActWork(returnValue, resolve2, reject) {
+      function recursivelyFlushAsyncActWork(returnValue, resolve3, reject) {
         {
           var queue = ReactCurrentActQueue.current;
           if (queue !== null) {
@@ -21090,16 +21848,16 @@ Check the top-level render call using <` + parentName + ">.";
               enqueueTask(function() {
                 if (queue.length === 0) {
                   ReactCurrentActQueue.current = null;
-                  resolve2(returnValue);
+                  resolve3(returnValue);
                 } else {
-                  recursivelyFlushAsyncActWork(returnValue, resolve2, reject);
+                  recursivelyFlushAsyncActWork(returnValue, resolve3, reject);
                 }
               });
             } catch (error2) {
               reject(error2);
             }
           } else {
-            resolve2(returnValue);
+            resolve3(returnValue);
           }
         }
       }
@@ -59172,8 +59930,8 @@ class Ink {
     }
   }
   async waitUntilExit() {
-    this.exitPromise ||= new Promise((resolve2, reject2) => {
-      this.resolveExitPromise = resolve2;
+    this.exitPromise ||= new Promise((resolve3, reject2) => {
+      this.resolveExitPromise = resolve3;
       this.rejectExitPromise = reject2;
     });
     return this.exitPromise;
@@ -59633,19 +60391,23 @@ var init_build2 = __esm(async () => {
 // packages/paths/src/paths.ts
 import { exists } from "fs/promises";
 import { homedir as homedir3 } from "os";
-import { basename, join as join4, resolve as resolve2 } from "path";
-async function findProjectRoot() {
-  let dir = process.cwd();
+import { basename, join as join4, resolve as resolve3 } from "path";
+async function findProjectRoot(startDir = process.cwd()) {
+  let dir = startDir;
   while (dir !== "/") {
-    if (await exists(join4(dir, "openspec")))
+    if (await exists(join4(dir, ROOT_MARKER)))
       return dir;
-    dir = resolve2(dir, "..");
+    dir = resolve3(dir, "..");
   }
-  return process.cwd();
+  return startDir;
 }
 function worktreesDir(projectRoot) {
   return join4(homedir3(), ".ralph", basename(projectRoot), "worktrees");
 }
+function setupBackupPath() {
+  return join4(homedir3(), ".ralph", "setup.tmp");
+}
+var ROOT_MARKER = "WORKFLOW.md";
 var init_paths = () => {};
 
 // node_modules/.bun/yaml@2.9.0/node_modules/yaml/dist/nodes/identity.js
@@ -80635,7 +81397,7 @@ var init_schema = __esm(() => {
     maxRuntimeMinutesPerTask: exports_external.number().nonnegative().default(0),
     maxConsecutiveFailuresPerTask: exports_external.number().int().nonnegative().default(5),
     iterationDelaySeconds: exports_external.number().int().nonnegative().default(0),
-    logRawStream: exports_external.boolean().default(false),
+    logRawStream: exports_external.boolean().default(true),
     taskVerbose: exports_external.boolean().default(false),
     enableManualTest: exports_external.boolean().default(false),
     useWorktree: exports_external.boolean().default(false),
@@ -80809,13 +81571,14 @@ maxConsecutiveFailuresPerTask: 5
 
 engine: claude
 model: opus
-logRawStream: false
+logRawStream: true
 taskVerbose: false
 
 useWorktree: false
 cleanupWorktreeOnSuccess: false
 
 createPrOnSuccess: false
+prDraft: true
 prBaseBranch: main
 stackPrsOnDependencies: false
 autoMergeStrategy: squash
@@ -80868,6 +81631,10 @@ linear:
     #   filter:
     #     - type: label
     #       value: "ralph:auto-merge"
+
+openspec:
+  reviewPhase:
+    enabled: true
 ---
 You are working on {{ issue.identifier }}: {{ issue.title }}.
 
@@ -81065,537 +81832,6 @@ function renderTemplate(src, ctx) {
   return renderNodes(tree, ctx);
 }
 
-// packages/workflow/src/fields.ts
-function fieldsForMode(mode, answers = {}, restrictTo) {
-  const all = mode === "customized" ? CUSTOMIZED_FIELDS : QUICK_FIELDS;
-  const allowed = restrictTo ? new Set(restrictTo) : null;
-  return all.filter((field) => {
-    if (allowed && !allowed.has(field.id))
-      return false;
-    return !field.when || field.when(answers);
-  });
-}
-function findField(id) {
-  return CUSTOMIZED_FIELDS.find((field) => field.id === id);
-}
-function modelOptionValues() {
-  const field = findField("model");
-  return field && field.spec.kind === "select" ? field.spec.options.map((o) => o.value) : [];
-}
-var PROMPT_BODY_FIELD_ID = "promptBody", REPO_LINK_FIELD_ID = "repo.link", AWAITING_STATUS_FIELD_ID = "linear.confirmationMode.awaitingStatus", yes = () => ({ kind: "confirm", defaultChoice: "confirm" }), no = () => ({ kind: "confirm", defaultChoice: "cancel" }), PROJECT_NAME, LINEAR_TEAM, REPO_LINK, LINEAR_FILTER, QUICK_FIELDS, isOn = (id) => (answers) => answers[id] === true, CUSTOMIZED_FIELDS, COMMON_CLI_OPTIONS, FIELD_DESCRIPTIONS;
-var init_fields = __esm(() => {
-  PROJECT_NAME = {
-    id: "project.name",
-    label: "Project name",
-    description: "The project's display name. Ralphy puts it in the agent's prompt and in its logs.",
-    spec: { kind: "text", placeholder: "my-project" }
-  };
-  LINEAR_TEAM = {
-    id: "linear.team",
-    label: "Linear team key",
-    hint: "e.g. ENG \u2014 leave blank to match all teams",
-    description: "The Linear team this repository is linked to, given by its key (e.g. ENG). Ralphy only picks up issues from this team. Leave blank to watch every team.",
-    emptyLabel: "all teams",
-    spec: { kind: "text" }
-  };
-  REPO_LINK = {
-    id: "repo.link",
-    label: "Link this repository to the team?",
-    description: "Record the detected git repository in WORKFLOW.md and link it to the Linear team above. Confirm to adopt the detected repo; decline to leave it out.",
-    spec: yes(),
-    when: (answers) => typeof answers["repo.name"] === "string" && answers["repo.name"] !== ""
-  };
-  LINEAR_FILTER = {
-    id: "linear.filter",
-    label: "Linear filter",
-    hint: "e.g. 'assignee = me', 'assignee = any', 'assignee = unassigned', or an email/user-id",
-    description: "Global filter applied to every Linear ticket fetch. The only clause today is 'assignee = <value>', where <value> is 'me' (issues assigned to you), 'any' (regardless of assignee), 'unassigned', a Linear user id, or an email. Blank defaults to 'assignee = me'.",
-    emptyLabel: "assignee = me",
-    spec: { kind: "text", placeholder: "assignee = me" }
-  };
-  QUICK_FIELDS = [PROJECT_NAME, LINEAR_TEAM, REPO_LINK, LINEAR_FILTER];
-  CUSTOMIZED_FIELDS = [
-    PROJECT_NAME,
-    {
-      id: "project.language",
-      label: "Language",
-      description: "Primary programming language (e.g. TypeScript). Added to the agent's prompt as context.",
-      spec: { kind: "text", placeholder: "TypeScript" }
-    },
-    {
-      id: "project.framework",
-      label: "Framework",
-      description: "Primary framework or toolchain (e.g. Bun + Nx). Added to the agent's prompt as context.",
-      spec: { kind: "text", placeholder: "Bun + Nx" }
-    },
-    {
-      id: "commands.test",
-      label: "Test command",
-      description: "Shell command Ralphy runs to check the agent's work each iteration; its exit code decides pass or fail.",
-      spec: { kind: "text", placeholder: "bun test" }
-    },
-    {
-      id: "commands.lint",
-      label: "Lint command",
-      description: "Shell command Ralphy runs to lint the code before a task is allowed to finish.",
-      spec: { kind: "text", placeholder: "bun run lint" }
-    },
-    {
-      id: "commands.build",
-      label: "Build command",
-      description: "Shell command Ralphy runs to confirm the project still compiles / builds.",
-      spec: { kind: "text", placeholder: "bun run build" }
-    },
-    {
-      id: "commands.typecheck",
-      label: "Typecheck command",
-      description: "Shell command Ralphy runs to confirm the project's types still pass.",
-      spec: { kind: "text", placeholder: "bun run typecheck" }
-    },
-    {
-      id: "engine",
-      label: "Engine",
-      description: "Which AI coding tool runs the loop: 'claude' (Claude Code) or 'codex' (OpenAI Codex).",
-      spec: {
-        kind: "select",
-        options: [
-          { label: "claude", value: "claude" },
-          { label: "codex", value: "codex" }
-        ]
-      }
-    },
-    {
-      id: "model",
-      label: "Model tier",
-      description: "Model tier the engine uses. 'opus' is the most capable, 'haiku' the cheapest and fastest; higher tiers cost more per token.",
-      spec: {
-        kind: "select",
-        options: [
-          { label: "opus", value: "opus" },
-          { label: "sonnet", value: "sonnet" },
-          { label: "haiku", value: "haiku" }
-        ]
-      }
-    },
-    {
-      id: "logRawStream",
-      label: "Log the raw engine stream to stdout?",
-      description: "Print the engine's raw event stream to the terminal. Very verbose \u2014 mainly for debugging.",
-      spec: no()
-    },
-    {
-      id: "taskVerbose",
-      label: "Pass --verbose to the task sub-process?",
-      description: "Run the per-task process with --verbose for extra diagnostic output.",
-      spec: no()
-    },
-    {
-      id: "concurrency",
-      label: "Concurrency (parallel tasks)",
-      description: "How many tasks Ralphy works on at once. Higher finishes faster but uses more API quota simultaneously.",
-      spec: { kind: "number", placeholder: "1" }
-    },
-    {
-      id: "pollIntervalSeconds",
-      label: "Poll interval (seconds)",
-      description: "In agent mode, how often (in seconds) Ralphy checks Linear for new issues to pick up.",
-      spec: { kind: "number", placeholder: "60" }
-    },
-    {
-      id: "iterationDelaySeconds",
-      label: "Delay between iterations (seconds)",
-      description: "Seconds to pause between loop iterations \u2014 a throttle to slow spend. 0 means no pause.",
-      spec: { kind: "number", placeholder: "0" }
-    },
-    {
-      id: "maxIterationsPerTask",
-      label: "Max iterations per task (0 = unlimited)",
-      description: "Stop a task after this many loop iterations. 0 means no limit (run until done or another limit hits).",
-      spec: { kind: "number", placeholder: "0" }
-    },
-    {
-      id: "maxCostUsdPerTask",
-      label: "Max cost USD per task (0 = unlimited)",
-      description: "Stop a task once its API spend passes this many US dollars. 0 means no cost limit.",
-      spec: { kind: "number", placeholder: "0" }
-    },
-    {
-      id: "maxRuntimeMinutesPerTask",
-      label: "Max runtime minutes per task (0 = unlimited)",
-      description: "Stop a task after this many minutes of wall-clock time. 0 means no time limit.",
-      spec: { kind: "number", placeholder: "0" }
-    },
-    {
-      id: "maxConsecutiveFailuresPerTask",
-      label: "Max consecutive identical failures",
-      description: "Give up on a task after this many identical failures in a row \u2014 a guard against stuck loops.",
-      spec: { kind: "number", placeholder: "5" }
-    },
-    {
-      id: "useWorktree",
-      label: "Run each task in an isolated git worktree?",
-      description: "Run each task in its own git worktree (a separate working copy of the repo) so parallel tasks don't overwrite each other's files.",
-      spec: no()
-    },
-    {
-      id: "cleanupWorktreeOnSuccess",
-      label: "Delete the worktree after a successful task?",
-      description: "Delete a task's worktree (its separate working copy) once it succeeds, to reclaim disk space.",
-      spec: no(),
-      when: isOn("useWorktree")
-    },
-    {
-      id: "setupScript",
-      label: "Setup script (runs before each task)",
-      description: "Shell script run once before each task starts \u2014 e.g. to install dependencies.",
-      spec: { kind: "text" }
-    },
-    {
-      id: "teardownScript",
-      label: "Teardown script (runs after each task)",
-      description: "Shell script run once after each task ends \u2014 e.g. to clean up temporary state.",
-      spec: { kind: "text" }
-    },
-    {
-      id: "enableManualTest",
-      label: "Enable the manual-test phase?",
-      description: "Add a phase that pauses for a human to manually test the change (e.g. in the UI) before the task is marked done.",
-      spec: no()
-    },
-    {
-      id: "appendPrompt",
-      label: "Extra text appended to every prompt",
-      description: "Free text added to the end of every prompt sent to the agent \u2014 house rules or reminders.",
-      spec: { kind: "text" }
-    },
-    {
-      id: "createPrOnSuccess",
-      label: "Open a pull request when a task succeeds?",
-      description: "When a task succeeds, automatically push the branch and open a GitHub pull request (PR).",
-      spec: no()
-    },
-    {
-      id: "prDraft",
-      label: "Open pull requests as drafts?",
-      description: "Open PRs as drafts (marked not-ready-for-review) instead of ready for review.",
-      spec: no(),
-      when: isOn("createPrOnSuccess")
-    },
-    {
-      id: "prBaseBranch",
-      label: "PR base branch",
-      description: "The branch new pull requests merge into (their base) \u2014 e.g. main.",
-      spec: { kind: "text", placeholder: "main" },
-      when: isOn("createPrOnSuccess")
-    },
-    {
-      id: "stackPrsOnDependencies",
-      label: "Stack dependent issues' PRs onto their blocker's PR?",
-      description: "If an issue is blocked by another that already has an open PR, base this issue's PR on that PR's branch instead of main (a 'stacked' PR).",
-      spec: no(),
-      when: isOn("createPrOnSuccess")
-    },
-    {
-      id: "autoMergeStrategy",
-      label: "Auto-merge strategy",
-      description: "How GitHub combines the PR's commits when it auto-merges: squash (one commit), merge (a merge commit), or rebase.",
-      spec: {
-        kind: "select",
-        options: [
-          { label: "squash", value: "squash" },
-          { label: "merge", value: "merge" },
-          { label: "rebase", value: "rebase" }
-        ]
-      },
-      when: isOn("createPrOnSuccess")
-    },
-    {
-      id: "manualMergeWhenAutoMergeDisabled",
-      label: "Merge manually when GitHub auto-merge is disabled?",
-      description: "If the repo doesn't have GitHub's auto-merge feature enabled, have Ralphy merge the PR itself once checks pass.",
-      spec: yes(),
-      when: isOn("createPrOnSuccess")
-    },
-    {
-      id: "finalizeNoOpAsDone",
-      label: "Finalize a no-op (meta-only) change as done?",
-      description: "If a change ended up touching only meta files (specs, task lists) and no real code, mark the issue done instead of retrying it.",
-      spec: yes()
-    },
-    {
-      id: "fixCiOnFailure",
-      label: "Let the agent fix CI failures?",
-      description: "After opening a PR, watch its CI (the automated checks GitHub runs) and let the agent push fixes when they fail.",
-      spec: no()
-    },
-    {
-      id: "maxCiFixAttempts",
-      label: "Max CI-fix attempts per task",
-      description: "Stop trying to fix failing CI after this many attempts.",
-      spec: { kind: "number", placeholder: "5" },
-      when: isOn("fixCiOnFailure")
-    },
-    {
-      id: "ciPollIntervalSeconds",
-      label: "CI status poll interval (seconds)",
-      description: "How often (in seconds) to re-check the PR's CI status while waiting on or fixing it.",
-      spec: { kind: "number", placeholder: "30" },
-      when: isOn("fixCiOnFailure")
-    },
-    {
-      id: "ignoreCiChecks",
-      label: "CI checks to ignore",
-      description: "Names of CI checks to ignore when deciding whether a PR is green \u2014 e.g. known-flaky jobs.",
-      spec: { kind: "list", placeholder: "check name" }
-    },
-    {
-      id: "rules",
-      label: "Project rules",
-      description: "House rules added to every prompt (e.g. 'never edit generated files'). One rule per entry.",
-      spec: { kind: "list", placeholder: "a rule" }
-    },
-    {
-      id: "boundaries.never_touch",
-      label: "Never-touch globs",
-      description: "Glob patterns for files the agent must never modify (e.g. dist/**).",
-      spec: { kind: "list", placeholder: "dist/**" }
-    },
-    LINEAR_TEAM,
-    REPO_LINK,
-    LINEAR_FILTER,
-    {
-      id: "linear.postComments",
-      label: "Post progress comments on the Linear issue?",
-      description: "Post progress comments on the Linear issue while a task runs.",
-      spec: yes()
-    },
-    {
-      id: "linear.updateEveryIterations",
-      label: "Post a progress update every N iterations (0 = off)",
-      description: "Post a progress comment every N loop iterations. 0 turns periodic updates off.",
-      spec: { kind: "number", placeholder: "10" }
-    },
-    {
-      id: "linear.mentionTrigger",
-      label: "Watch comments/PRs for @mentions?",
-      description: "Watch a finished issue's comments and its PR for @mentions of Ralphy, and re-engage when mentioned.",
-      spec: yes()
-    },
-    {
-      id: "linear.mentionHandle",
-      label: "Mention handle",
-      description: "The @handle that, when mentioned, makes Ralphy pick the issue back up (e.g. @ralphy).",
-      spec: { kind: "text", placeholder: "@ralphy" },
-      when: isOn("linear.mentionTrigger")
-    },
-    {
-      id: "linear.codeReviewTrigger",
-      label: "Watch PRs for unresolved review threads?",
-      description: "Watch open PRs for unresolved review comments and re-engage to address them.",
-      spec: yes()
-    },
-    {
-      id: "linear.codeReviewStaleHours",
-      label: "Code-review stale window (hours)",
-      description: "Ignore review comments older than this many hours, so stale threads don't re-trigger work.",
-      spec: { kind: "number", placeholder: "24" },
-      when: isOn("linear.codeReviewTrigger")
-    },
-    {
-      id: "linear.syncTasksToComment",
-      label: "Mirror tasks.md into a sticky Linear comment?",
-      description: "Keep one pinned ('sticky') Linear comment in sync with the task checklist (tasks.md).",
-      spec: yes()
-    },
-    {
-      id: "linear.syncSpecsAsAttachments",
-      label: "Upload proposal.md / design.md as attachments?",
-      description: "Upload the OpenSpec planning docs (proposal.md, design.md) to the issue as attachments. OpenSpec is Ralphy's spec-driven planning format.",
-      spec: yes()
-    },
-    {
-      id: "linear.specAttachmentFormats",
-      label: "Spec attachment formats",
-      description: "Which formats to upload the spec docs in: 'md' (raw markdown), 'pdf' (a rendered PDF), or both.",
-      spec: {
-        kind: "multiselect",
-        options: [
-          { label: "md", value: "md" },
-          { label: "pdf", value: "pdf" }
-        ]
-      },
-      when: isOn("linear.syncSpecsAsAttachments")
-    },
-    {
-      id: "linear.confirmationMode.enabled",
-      label: "Enable the human confirmation gate?",
-      description: "Pause after the agent finishes planning and wait for a human to approve before it writes any code (a confirmation gate).",
-      spec: no()
-    },
-    {
-      id: "linear.confirmationMode.timeoutHours",
-      label: "Confirmation timeout (hours)",
-      description: "If no one approves or rejects within this many hours, auto-resolve the confirmation gate.",
-      spec: { kind: "number", placeholder: "48" },
-      when: isOn("linear.confirmationMode.enabled")
-    },
-    {
-      id: "linear.confirmationMode.maxConfirmationRounds",
-      label: "Max confirmation rounds",
-      description: "How many times the plan can be revised and re-submitted for approval before Ralphy gives up.",
-      spec: { kind: "number", placeholder: "3" },
-      when: isOn("linear.confirmationMode.enabled")
-    },
-    {
-      id: AWAITING_STATUS_FIELD_ID,
-      label: "Park awaiting-approval tickets in a status?",
-      hint: "e.g. Planned \u2014 blank keeps them In Progress",
-      description: "When the confirmation gate opens, move the ticket to this Linear status so the board shows it waiting on a human (it must be a real status in your team). Ralphy also adds it to the in-progress pickup filter so the parked ticket keeps being polled, and re-asserts In Progress on approval. Leave blank to keep parked tickets in In Progress. Pairs with status-based indicators.",
-      spec: { kind: "text", placeholder: "Planned" },
-      when: isOn("linear.confirmationMode.enabled")
-    },
-    {
-      id: "linear.indicators",
-      label: "Linear lifecycle indicators",
-      description: "How Ralphy maps lifecycle events to Linear statuses/labels \u2014 which issues to pick up (todo) and what to set when a task is in progress, done, or errored.",
-      spec: { kind: "indicators" }
-    },
-    {
-      id: "preExistingErrorCheck.enabled",
-      label: "Enable the base-branch health gate?",
-      description: "Before picking up new work, run health-check commands on the base branch and pause if it's already broken, so the agent isn't blamed for pre-existing failures.",
-      spec: no()
-    },
-    {
-      id: "preExistingErrorCheck.commands",
-      label: "Health-gate commands (blank = use lint/test)",
-      description: "Commands run against the base branch to judge its health. Leave empty to reuse your lint/test commands.",
-      spec: { kind: "list", placeholder: "bun run lint" },
-      when: isOn("preExistingErrorCheck.enabled")
-    },
-    {
-      id: "preExistingErrorCheck.baseBranch",
-      label: "Health-gate base branch",
-      description: "The branch the health gate checks out and tests (usually main).",
-      spec: { kind: "text", placeholder: "main" },
-      when: isOn("preExistingErrorCheck.enabled")
-    },
-    {
-      id: "preExistingErrorCheck.label",
-      label: "Health-gate Linear label",
-      description: "Linear label applied to the ticket Ralphy opens when the base branch is found broken.",
-      spec: { kind: "text", placeholder: "ralph:pre-existing-error" },
-      when: isOn("preExistingErrorCheck.enabled")
-    },
-    {
-      id: "prTracker.enabled",
-      label: "Enable the PR tracker?",
-      description: "Keep watching the PRs Ralphy opened and automatically try to recover any whose merge state goes red (conflicts or failing CI).",
-      spec: yes()
-    },
-    {
-      id: "prTracker.maxRecoveryAttempts",
-      label: "PR tracker max recovery attempts",
-      description: "Give up auto-recovering a red PR after this many attempts, then flag it for a human.",
-      spec: { kind: "number", placeholder: "3" },
-      when: isOn("prTracker.enabled")
-    },
-    {
-      id: "prTracker.advanceMergedToDone",
-      label: "Advance merged PRs to done automatically?",
-      description: "Move an issue to its done state as soon as its PR is merged.",
-      spec: no(),
-      when: isOn("prTracker.enabled")
-    },
-    {
-      id: "metaPrompt.enabled",
-      label: "Enable the meta-prompt addendum?",
-      description: "Add Ralphy's task-level 'meta-prompt' layer (extra framing instructions) to each phase. Leave on unless you want raw prompts.",
-      spec: yes()
-    },
-    {
-      id: "metaPrompt.effort",
-      label: "Per-ticket effort tier",
-      description: "How much effort the meta-prompt nudges the agent toward per ticket. 'auto' detects it from the ticket; 'light'/'standard'/'heavy' pin every ticket to that tier.",
-      spec: {
-        kind: "select",
-        options: [
-          { label: "auto", value: "auto" },
-          { label: "light", value: "light" },
-          { label: "standard", value: "standard" },
-          { label: "heavy", value: "heavy" }
-        ]
-      },
-      when: isOn("metaPrompt.enabled")
-    },
-    {
-      id: "openspec.reviewPhase.enabled",
-      label: "Enable the OpenSpec review phase?",
-      description: "After all tasks finish, spawn a separate reviewer agent that reads the full diff and writes review findings; open findings loop back into more work.",
-      spec: no()
-    },
-    {
-      id: "openspec.reviewPhase.maxRounds",
-      label: "Review phase max rounds",
-      description: "How many review\u2192fix cycles to run before the change is archived regardless.",
-      spec: { kind: "number", placeholder: "1" },
-      when: isOn("openspec.reviewPhase.enabled")
-    },
-    {
-      id: "openspec.reviewPhase.reviewerModel",
-      label: "Reviewer model (blank = same as main)",
-      description: "Model used for the review pass. Blank reuses the main model; a cheaper tier (e.g. haiku) saves cost.",
-      spec: { kind: "text", placeholder: "haiku" },
-      when: isOn("openspec.reviewPhase.enabled")
-    },
-    {
-      id: "openspec.reviewPhase.reviewerContextStrategy",
-      label: "Reviewer context",
-      description: "'fresh' gives the reviewer a brand-new session (unbiased); 'warm' resumes the last task's session (more context, cheaper).",
-      spec: {
-        kind: "select",
-        options: [
-          { label: "fresh", value: "fresh" },
-          { label: "warm", value: "warm" }
-        ]
-      },
-      when: isOn("openspec.reviewPhase.enabled")
-    },
-    {
-      id: PROMPT_BODY_FIELD_ID,
-      label: "Customize the prompt sent to the agent?",
-      description: "The prompt the agent receives lives in the file body \u2014 a template filled with per-issue values (e.g. {{ issue.identifier }}). Edit it here, or leave it and finish to keep the default.",
-      spec: { kind: "multiline" }
-    }
-  ];
-  COMMON_CLI_OPTIONS = [
-    { fieldId: "model", flag: "--model", argKey: "model", kind: "model" },
-    { fieldId: "iterationDelaySeconds", flag: "--delay", argKey: "delay", kind: "int" },
-    { fieldId: "maxCostUsdPerTask", flag: "--max-cost", argKey: "maxCostUsd", kind: "float" },
-    {
-      fieldId: "maxRuntimeMinutesPerTask",
-      flag: "--max-runtime",
-      argKey: "maxRuntimeMinutes",
-      kind: "float"
-    },
-    {
-      fieldId: "maxConsecutiveFailuresPerTask",
-      flag: "--max-failures",
-      argKey: "maxConsecutiveFailures",
-      kind: "int"
-    },
-    {
-      fieldId: "maxIterationsPerTask",
-      flag: "--max-iterations",
-      argKey: "maxIterations",
-      kind: "int"
-    },
-    { fieldId: "logRawStream", flag: "--log", argKey: "log", kind: "boolean" },
-    { fieldId: "taskVerbose", flag: "--verbose", argKey: "verbose", kind: "boolean" }
-  ];
-  FIELD_DESCRIPTIONS = CUSTOMIZED_FIELDS.filter((field) => Boolean(field.description) && field.spec.kind !== "multiline").map((field) => ({ path: field.id.split("."), description: field.description }));
-});
-
 // packages/workflow/src/wizard.ts
 function indicatorsForPreset(preset) {
   if (preset === "status-standard") {
@@ -81689,6 +81925,87 @@ var init_wizard = __esm(() => {
   import_yaml = __toESM(require_dist(), 1);
 });
 
+// packages/workflow/src/migrate/normalize.ts
+function defaultLeafEntries() {
+  const defaults2 = WorkflowConfigSchema.parse({});
+  const entries = [];
+  const walk = (node2, prefix) => {
+    if (Array.isArray(node2)) {
+      entries.push({ path: prefix, value: node2 });
+      return;
+    }
+    if (node2 && typeof node2 === "object") {
+      const keys2 = Object.keys(node2);
+      if (keys2.length === 0)
+        return;
+      for (const key of keys2)
+        walk(node2[key], [...prefix, key]);
+      return;
+    }
+    entries.push({ path: prefix, value: node2 });
+  };
+  walk(defaults2, []);
+  return entries.filter((entry) => !(entry.path.length === 1 && entry.path[0] === "version"));
+}
+function stampDescription(document2, path) {
+  const match = FIELD_DESCRIPTIONS.find((description) => description.path.length === path.length && description.path.every((segment, index) => segment === path[index]));
+  if (!match)
+    return;
+  const parent = path.length === 1 ? document2.contents : document2.getIn(path.slice(0, -1), true);
+  if (!import_yaml2.default.isMap(parent))
+    return;
+  const leaf = path[path.length - 1];
+  const pair = parent.items.find((item) => import_yaml2.default.isScalar(item.key) && String(item.key.value) === leaf);
+  if (!pair || !import_yaml2.default.isScalar(pair.key))
+    return;
+  pair.key.commentBefore = toCommentLines(match.description);
+}
+function normalizeWorkflowMarkdown(markdown) {
+  const match = FRONTMATTER_RE.exec(markdown);
+  if (!match)
+    return { markdown, changed: false, added: [] };
+  const document2 = import_yaml2.default.parseDocument(match[1] ?? "");
+  if (!import_yaml2.default.isMap(document2.contents))
+    return { markdown, changed: false, added: [] };
+  const body = match[2] ?? "";
+  const added = [];
+  for (const { path, value } of defaultLeafEntries()) {
+    if (document2.getIn(path) !== undefined)
+      continue;
+    document2.setIn(path, value);
+    stampDescription(document2, path);
+    added.push(path.join("."));
+  }
+  const gateEnabled = document2.getIn(["linear", "confirmationMode", "enabled"]) === true;
+  const hasGetApproved = document2.getIn(["linear", "indicators", "getApproved"]) !== undefined;
+  if (gateEnabled && !hasGetApproved) {
+    document2.setIn(["linear", "indicators", "getApproved"], DEFAULT_APPROVAL_INDICATORS.getApproved);
+    if (document2.getIn(["linear", "indicators", "clearApproved"]) === undefined) {
+      document2.setIn(["linear", "indicators", "clearApproved"], DEFAULT_APPROVAL_INDICATORS.clearApproved);
+    }
+    added.push("linear.indicators.getApproved");
+  }
+  if (added.length === 0)
+    return { markdown, changed: false, added: [] };
+  const frontmatter = document2.toString({ flowCollectionPadding: false }).replace(/\n+$/, "");
+  return { markdown: `---
+${frontmatter}
+---
+${body}`, changed: true, added };
+}
+var import_yaml2, DEFAULT_APPROVAL_INDICATORS;
+var init_normalize = __esm(() => {
+  init_schema();
+  init_default();
+  init_fields();
+  init_wizard();
+  import_yaml2 = __toESM(require_dist(), 1);
+  DEFAULT_APPROVAL_INDICATORS = {
+    getApproved: { filter: [{ type: "label", value: "approved" }] },
+    clearApproved: { type: "label", value: "approved" }
+  };
+});
+
 // packages/workflow/src/confirmation.ts
 function matchesIndicator(indicator, ticket) {
   if (!indicator || indicator.filter.length === 0)
@@ -81796,6 +82113,7 @@ __export(exports_workflow, {
   renderTemplate: () => renderTemplate,
   parseWorkflow: () => parseWorkflow,
   parseLinearFilter: () => parseLinearFilter,
+  normalizeWorkflowMarkdown: () => normalizeWorkflowMarkdown,
   matchesIndicator: () => matchesIndicator,
   loadWorkflow: () => loadWorkflow,
   ensureWorkflow: () => ensureWorkflow,
@@ -81805,6 +82123,7 @@ __export(exports_workflow, {
   WORKFLOW_FILE: () => WORKFLOW_FILE,
   FRONTMATTER_RE: () => FRONTMATTER_RE,
   DEFAULT_WORKFLOW_MD: () => DEFAULT_WORKFLOW_MD,
+  DEFAULT_APPROVAL_INDICATORS: () => DEFAULT_APPROVAL_INDICATORS,
   CURRENT_WORKFLOW_VERSION: () => CURRENT_WORKFLOW_VERSION
 });
 import { join as join5 } from "path";
@@ -81818,7 +82137,7 @@ function parseWorkflow(text, path = "") {
   const body = m[2] ?? "";
   let raw;
   try {
-    raw = import_yaml2.default.parse(yamlText, { schema: "core" });
+    raw = import_yaml3.default.parse(yamlText, { schema: "core" });
   } catch (err) {
     throw new Error(`WORKFLOW.md frontmatter is not valid YAML.
 ` + (path ? `  File: ${path}
@@ -81906,21 +82225,24 @@ function applyAliases(cfg) {
     }
   }
 }
-function workflowPath(projectRoot) {
-  return join5(projectRoot, WORKFLOW_FILE);
+function workflowPath(projectRoot, workflowFile) {
+  return workflowFile ?? join5(projectRoot, WORKFLOW_FILE);
 }
-async function loadWorkflow(projectRoot) {
-  const path = workflowPath(projectRoot);
+async function loadWorkflow(projectRoot, workflowFile, options = {}) {
+  const path = workflowPath(projectRoot, workflowFile);
   const file2 = Bun.file(path);
   if (!await file2.exists()) {
     const { config: config2 } = parseWorkflow(DEFAULT_WORKFLOW_MD);
     return { config: config2, body: extractDefaultBody(), path };
   }
   const text = await file2.text();
-  return parseWorkflow(text, path);
+  const normalized = normalizeWorkflowMarkdown(text);
+  if (normalized.changed && options.persist)
+    await Bun.write(path, normalized.markdown);
+  return parseWorkflow(normalized.markdown, path);
 }
-async function ensureWorkflow(projectRoot) {
-  const path = workflowPath(projectRoot);
+async function ensureWorkflow(projectRoot, workflowFile) {
+  const path = workflowPath(projectRoot, workflowFile);
   const file2 = Bun.file(path);
   if (await file2.exists())
     return path;
@@ -81952,15 +82274,17 @@ function renderWorkflowPrompt(workflow, ctx) {
   };
   return renderTemplate(workflow.body, fullCtx);
 }
-var import_yaml2, WORKFLOW_FILE = "WORKFLOW.md";
+var import_yaml3, WORKFLOW_FILE = "WORKFLOW.md";
 var init_workflow = __esm(() => {
   init_schema();
   init_default();
   init_wizard();
+  init_normalize();
   init_schema();
   init_default();
   init_linear_filter();
-  import_yaml2 = __toESM(require_dist(), 1);
+  init_normalize();
+  import_yaml3 = __toESM(require_dist(), 1);
 });
 
 // packages/core/src/repo/index.ts
@@ -82911,6 +83235,24 @@ function resolveIndicators(value) {
 }
 function buildFromAnswers(mode, answers, build = buildWorkflowMarkdown) {
   const values2 = { ...answers };
+  const concurrencyValue = values2["concurrency"];
+  if (typeof concurrencyValue === "number" && concurrencyValue > 1) {
+    values2["useWorktree"] = true;
+  }
+  const assigneeChoice = values2[LINEAR_ASSIGNEE_CHOICE_FIELD_ID];
+  if (typeof assigneeChoice === "string") {
+    let assignee;
+    if (assigneeChoice === "other") {
+      const raw = values2[LINEAR_ASSIGNEE_VALUE_FIELD_ID];
+      assignee = typeof raw === "string" && raw.trim() !== "" ? raw.trim() : undefined;
+    } else {
+      assignee = assigneeChoice;
+    }
+    if (assignee)
+      values2["linear.filter"] = `assignee = ${assignee}`;
+  }
+  delete values2[LINEAR_ASSIGNEE_CHOICE_FIELD_ID];
+  delete values2[LINEAR_ASSIGNEE_VALUE_FIELD_ID];
   if ("linear.indicators" in values2) {
     const indicators = resolveIndicators(values2["linear.indicators"]);
     if (indicators)
@@ -82926,20 +83268,20 @@ function buildFromAnswers(mode, answers, build = buildWorkflowMarkdown) {
       values2["linear.indicators"] = map3;
     }
   }
-  const parkStatusRaw = values2[AWAITING_STATUS_FIELD_ID];
-  const parkStatus = typeof parkStatusRaw === "string" ? parkStatusRaw.trim() : "";
-  if (values2["linear.confirmationMode.enabled"] === true && parkStatus && values2["linear.indicators"] && typeof values2["linear.indicators"] === "object") {
+  if (values2["linear.confirmationMode.enabled"] === true && values2["linear.indicators"] && typeof values2["linear.indicators"] === "object") {
     const map3 = { ...values2["linear.indicators"] };
-    map3.setAwaitingConfirmation = { type: "status", value: parkStatus };
-    const existing = map3.getInProgress;
-    const filter2 = existing && !Array.isArray(existing) && "filter" in existing ? [...existing.filter] : [];
-    if (!filter2.some((m) => m.type === "status" && m.value === parkStatus)) {
-      filter2.push({ type: "status", value: parkStatus });
+    const awaiting = map3.setAwaitingConfirmation;
+    const parkMarker = Array.isArray(awaiting) ? awaiting.find((marker) => marker.type === "status") : awaiting;
+    if (parkMarker && !Array.isArray(parkMarker) && "type" in parkMarker && parkMarker.type === "status") {
+      const existing = map3.getInProgress;
+      const filter2 = existing && !Array.isArray(existing) && "filter" in existing ? [...existing.filter] : [];
+      if (!filter2.some((marker) => marker.type === "status" && marker.value === parkMarker.value)) {
+        filter2.push({ type: "status", value: parkMarker.value });
+        map3.getInProgress = { filter: filter2 };
+        values2["linear.indicators"] = map3;
+      }
     }
-    map3.getInProgress = { filter: filter2 };
-    values2["linear.indicators"] = map3;
   }
-  delete values2[AWAITING_STATUS_FIELD_ID];
   const linkRepo = values2[REPO_LINK_FIELD_ID] === true;
   delete values2[REPO_LINK_FIELD_ID];
   if (!linkRepo) {
@@ -83028,7 +83370,8 @@ function SetupWizard({
   buildMarkdown,
   onlyFields,
   initialBody,
-  detectedRepo
+  detectedRepo,
+  onAnswersChange
 }) {
   const { exit } = use_app_default();
   const startValues = initialValues ?? {};
@@ -83103,6 +83446,7 @@ function SetupWizard({
     setAnswers(source);
     setIndex(target);
     initEditing(fieldsFor(mode, source)[target], source);
+    onAnswersChange?.({ mode, values: source });
   };
   const valuesToWrite = (source) => {
     if (!onlyFields)
@@ -83140,6 +83484,7 @@ function SetupWizard({
         setIndex(0);
         setVisited(new Set([fieldsFor(chosen, answers)[0].id]));
         initEditing(fieldsFor(chosen, answers)[0], answers);
+        onAnswersChange?.({ mode: chosen, values: answers });
       }
       return;
     }
@@ -83240,7 +83585,15 @@ ${draft.slice(at2)}`, at2 + 1);
             /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
               bold: true,
               children: "Ralphy setup"
-            }, undefined, false, undefined, this)
+            }, undefined, false, undefined, this),
+            /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
+              dimColor: true,
+              children: [
+                "  \xB7  ",
+                "v",
+                VERSION
+              ]
+            }, undefined, true, undefined, this)
           ]
         }, undefined, true, undefined, this),
         /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
@@ -83301,6 +83654,9 @@ ${draft.slice(at2)}`, at2 + 1);
           /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
             dimColor: true,
             children: [
+              "  \xB7  ",
+              "v",
+              VERSION,
               "  \xB7  ",
               mode,
               " \xB7 step ",
@@ -83393,7 +83749,7 @@ function hintFor(kind) {
     return `\u2191\u2193 to switch \xB7 enter to confirm and continue \xB7 ${nav}`;
   }
   if (kind === "multiselect") {
-    return `\u2191\u2193 to move \xB7 space to toggle \xB7 enter to confirm and continue \xB7 ${nav}`;
+    return `\u2191\u2193 to move \xB7 space to select \xB7 enter to confirm \xB7 ${nav}`;
   }
   if (kind === "list") {
     return `type + enter to add \xB7 empty enter to finish \xB7 ${nav}`;
@@ -83656,6 +84012,16 @@ function ChoicePrompt({
     ]
   }, undefined, true, undefined, this);
 }
+function ResumeOrFreshPrompt({
+  onChoice
+}) {
+  return /* @__PURE__ */ jsx_dev_runtime.jsxDEV(ChoicePrompt, {
+    title: "Unfinished setup found",
+    subtitle: "A previous setup session was interrupted \u2014 resume it or start over",
+    options: RESUME_FRESH_OPTIONS,
+    onChoice
+  }, undefined, false, undefined, this);
+}
 function EditOrExitPrompt({ onChoice }) {
   return /* @__PURE__ */ jsx_dev_runtime.jsxDEV(ChoicePrompt, {
     title: "WORKFLOW.md already exists",
@@ -83831,9 +84197,7 @@ function IndicatorBuilder({
           /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
             dimColor: true,
             children: [
-              "  \xB7  ",
-              state.label,
-              " \xB7 ",
+              "  \xB7  step ",
               stateIndex + 1,
               "/",
               states.length
@@ -83841,6 +84205,16 @@ function IndicatorBuilder({
           }, undefined, true, undefined, this)
         ]
       }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
+        children: [
+          "  Configuring: ",
+          /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
+            bold: true,
+            color: "cyan",
+            children: state.label
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
       /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
         dimColor: true,
         children: [
@@ -83862,8 +84236,15 @@ function IndicatorBuilder({
         children: phase === "type" ? /* @__PURE__ */ jsx_dev_runtime.jsxDEV(jsx_dev_runtime.Fragment, {
           children: [
             /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
-              children: "Choose a marker type for this state (or skip):"
-            }, undefined, false, undefined, this),
+              children: [
+                "Choose a marker type for ",
+                /* @__PURE__ */ jsx_dev_runtime.jsxDEV(Text, {
+                  bold: true,
+                  children: state.label
+                }, undefined, false, undefined, this),
+                " (or skip):"
+              ]
+            }, undefined, true, undefined, this),
             /* @__PURE__ */ jsx_dev_runtime.jsxDEV(OptionList, {
               options: typeChoices,
               highlight: typeIndex
@@ -83908,8 +84289,9 @@ function IndicatorBuilder({
     ]
   }, undefined, true, undefined, this);
 }
-var import_react22, jsx_dev_runtime, REPO_ANSWER_IDS, MODE_OPTIONS, INDICATOR_OPTIONS, CONFIRM_OPTIONS, EDIT_EXIT_OPTIONS, RECREATE_EXIT_OPTIONS, MIGRATE_OPTIONS, CORE_STATES, CONFIRMATION_STATES, ALL_TYPES;
+var import_react22, jsx_dev_runtime, REPO_ANSWER_IDS, MODE_OPTIONS, INDICATOR_OPTIONS, CONFIRM_OPTIONS, RESUME_FRESH_OPTIONS, EDIT_EXIT_OPTIONS, RECREATE_EXIT_OPTIONS, MIGRATE_OPTIONS, CORE_STATES, CONFIRMATION_STATES, ALL_TYPES;
 var init_SetupWizard = __esm(async () => {
+  init_version();
   init_wizard();
   init_fields();
   await init_build2();
@@ -83923,14 +84305,18 @@ var init_SetupWizard = __esm(async () => {
   ];
   INDICATOR_OPTIONS = [
     { label: "None \u2014 configure later in WORKFLOW.md", value: "none" },
-    { label: "Status-based (Todo \u2192 In Progress \u2192 In Review)", value: "status-standard" },
-    { label: "Label-based (ralph:todo / in-progress / done)", value: "label-standard" },
-    { label: "Custom \u2014 build markers per lifecycle slot", value: "custom" }
+    { label: "Status-based preset (Todo \u2192 In Progress \u2192 In Review)", value: "status-standard" },
+    { label: "Label-based preset (ralph:todo / in-progress / done)", value: "label-standard" },
+    { label: "Custom \u2014 open a guided builder (enter opens it)", value: "custom" }
   ];
   CONFIRM_OPTIONS = [
     { label: "Yes", value: "true" },
     { label: "No", value: "false" }
   ];
+  RESUME_FRESH_OPTIONS = [
+    { label: "Resume where I left off", value: "resume" },
+    { label: "Start fresh (discard the saved answers)", value: "fresh" }
+  ];
   EDIT_EXIT_OPTIONS = [
     { label: "Edit it with the setup wizard", value: "edit" },
     { label: "Exit without changes", value: "exit" }
@@ -84056,7 +84442,7 @@ var init_migrations = __esm(() => {
     {
       version: 3,
       description: "The per-workflow `linear.assignee` setting is replaced by a global " + "`linear.filter` expression (e.g. `assignee = me`) applied to every " + "ticket fetch. Existing `assignee` values are folded in automatically; " + "note that an empty filter now defaults to `assignee = me` (it previously " + "meant unassigned-only).",
-      fields: ["linear.filter"]
+      fields: ["linear.assigneeChoice", "linear.assigneeValue"]
     },
     {
       version: 4,
@@ -84067,6 +84453,129 @@ var init_migrations = __esm(() => {
   LATEST_MIGRATION_VERSION = MIGRATIONS.reduce((max2, migration) => Math.max(max2, migration.version), 0);
 });
 
+// apps/init/src/project-detect.ts
+import { join as join6 } from "path";
+async function readPackageJson(projectRoot) {
+  const file2 = Bun.file(join6(projectRoot, "package.json"));
+  if (!await file2.exists())
+    return null;
+  try {
+    return JSON.parse(await file2.text());
+  } catch {
+    return null;
+  }
+}
+async function fileExists(projectRoot, name) {
+  return Bun.file(join6(projectRoot, name)).exists();
+}
+async function detectRunPrefix(projectRoot) {
+  const lockfiles = [
+    { file: "bun.lock", prefix: "bun run" },
+    { file: "bun.lockb", prefix: "bun run" },
+    { file: "pnpm-lock.yaml", prefix: "pnpm run" },
+    { file: "yarn.lock", prefix: "yarn run" },
+    { file: "package-lock.json", prefix: "npm run" }
+  ];
+  for (const { file: file2, prefix } of lockfiles) {
+    if (await fileExists(projectRoot, file2))
+      return prefix;
+  }
+  return "bun run";
+}
+async function detectCommandsFromPackageJson(projectRoot) {
+  const pkg = await readPackageJson(projectRoot);
+  const scripts = pkg?.scripts ?? {};
+  const runPrefix = await detectRunPrefix(projectRoot);
+  const commands = {};
+  for (const { field, scripts: names } of COMMAND_FIELD_SCRIPTS) {
+    const name = names.find((candidate) => typeof scripts[candidate] === "string" && scripts[candidate] !== "");
+    if (name)
+      commands[field] = `${runPrefix} ${name}`;
+  }
+  return commands;
+}
+async function detectFramework(projectRoot) {
+  const pkg = await readPackageJson(projectRoot);
+  const dependencies = { ...pkg?.dependencies, ...pkg?.devDependencies };
+  const detected = [];
+  if (await fileExists(projectRoot, "bun.lock") || await fileExists(projectRoot, "bun.lockb")) {
+    detected.push("Bun");
+  }
+  if (await fileExists(projectRoot, "nx.json"))
+    detected.push("Nx");
+  for (const { dependency, name } of FRAMEWORK_MARKERS) {
+    if (dependencies[dependency] && !detected.includes(name)) {
+      detected.push(name);
+      break;
+    }
+  }
+  return detected.length > 0 ? detected.join(" + ") : undefined;
+}
+async function gitText(projectRoot, args) {
+  try {
+    const proc = Bun.spawn({
+      cmd: ["git", ...args],
+      cwd: projectRoot,
+      stdout: "pipe",
+      stderr: "ignore",
+      stdin: "ignore"
+    });
+    const out = await new Response(proc.stdout).text();
+    await proc.exited;
+    return out.trim();
+  } catch {
+    return "";
+  }
+}
+async function detectDefaultBranch(projectRoot) {
+  const head3 = await gitText(projectRoot, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+  if (head3) {
+    const branch = head3.replace(/^origin\//, "").trim();
+    if (branch)
+      return branch;
+  }
+  for (const candidate of ["main", "master"]) {
+    const verified = await gitText(projectRoot, ["rev-parse", "--verify", "--quiet", candidate]);
+    if (verified)
+      return candidate;
+  }
+  return;
+}
+async function detectInitialValues(projectRoot) {
+  const values2 = { ...await detectCommandsFromPackageJson(projectRoot) };
+  const framework = await detectFramework(projectRoot);
+  if (framework)
+    values2["project.framework"] = framework;
+  const defaultBranch = await detectDefaultBranch(projectRoot);
+  if (defaultBranch)
+    values2["prBaseBranch"] = defaultBranch;
+  return values2;
+}
+var COMMAND_FIELD_SCRIPTS, FRAMEWORK_MARKERS;
+var init_project_detect = __esm(() => {
+  COMMAND_FIELD_SCRIPTS = [
+    { field: "commands.test", scripts: ["test"] },
+    { field: "commands.lint", scripts: ["lint"] },
+    { field: "commands.build", scripts: ["build"] },
+    { field: "commands.typecheck", scripts: ["typecheck", "type-check", "tsc"] }
+  ];
+  FRAMEWORK_MARKERS = [
+    { dependency: "next", name: "Next.js" },
+    { dependency: "@remix-run/react", name: "Remix" },
+    { dependency: "@nestjs/core", name: "NestJS" },
+    { dependency: "@angular/core", name: "Angular" },
+    { dependency: "@sveltejs/kit", name: "SvelteKit" },
+    { dependency: "svelte", name: "Svelte" },
+    { dependency: "nuxt", name: "Nuxt" },
+    { dependency: "vue", name: "Vue" },
+    { dependency: "astro", name: "Astro" },
+    { dependency: "react", name: "React" },
+    { dependency: "@nestjs/common", name: "NestJS" },
+    { dependency: "fastify", name: "Fastify" },
+    { dependency: "express", name: "Express" }
+  ];
+});
+
 // apps/init/src/index.ts
 var exports_src = {};
 __export(exports_src, {
@@ -84074,6 +84583,33 @@ __export(exports_src, {
   maybeRunSetupWizard: () => maybeRunSetupWizard,
   main: () => main
 });
+async function readSetupBackup(projectRoot) {
+  const file2 = Bun.file(setupBackupPath());
+  if (!await file2.exists())
+    return null;
+  try {
+    const data = JSON.parse(await file2.text());
+    if (data.projectRoot !== projectRoot)
+      return null;
+    if (data.mode !== "quick" && data.mode !== "permissive" && data.mode !== "customized") {
+      return null;
+    }
+    if (!data.values || typeof data.values !== "object")
+      return null;
+    return { mode: data.mode, values: data.values };
+  } catch {
+    return null;
+  }
+}
+async function writeSetupBackup(projectRoot, mode, values2) {
+  const backup = { projectRoot, mode, values: values2 };
+  await Bun.write(setupBackupPath(), JSON.stringify(backup, null, 2));
+}
+async function clearSetupBackup() {
+  const file2 = Bun.file(setupBackupPath());
+  if (await file2.exists())
+    await file2.delete();
+}
 function withDetectedRepo(initial2, repo) {
   if (!repo)
     return initial2;
@@ -84094,7 +84630,7 @@ async function runSetupWizard(projectRoot, options = {}) {
   let markdown = null;
   const buildMarkdown = options.existing ? (answers, bodyOverride) => applyAnswersToWorkflow(options.existing, answers, bodyOverride) : undefined;
   const initialBody = workflowBody(options.existing ?? DEFAULT_WORKFLOW_MD);
-  const initialValues = withDetectedRepo(options.initialValues, options.detectedRepo);
+  const initialValues = options.resumeValues ?? withDetectedRepo(options.initialValues, options.detectedRepo);
   clearScreen2();
   const { waitUntilExit } = render_default(import_react23.createElement(SetupWizard, {
     onComplete: (md) => {
@@ -84108,21 +84644,33 @@ async function runSetupWizard(projectRoot, options = {}) {
     ...initialValues ? { initialValues } : {},
     ...options.onlyFields ? { onlyFields: options.onlyFields } : {},
     ...options.detectedRepo ? { detectedRepo: { owner: options.detectedRepo.owner, name: options.detectedRepo.name } } : {},
-    ...buildMarkdown ? { buildMarkdown } : {}
+    ...buildMarkdown ? { buildMarkdown } : {},
+    ...options.trackBackup ? {
+      onAnswersChange: (state) => {
+        writeSetupBackup(projectRoot, state.mode, state.values);
+      }
+    } : {}
   }));
   await waitUntilExit();
   if (markdown === null)
     return false;
-  await Bun.write(workflowPath(projectRoot), markdown);
+  const { markdown: healed } = normalizeWorkflowMarkdown(markdown);
+  await Bun.write(workflowPath(projectRoot, options.workflowFile), healed);
+  await clearSetupBackup();
   return true;
 }
-async function maybeRunSetupWizard(projectRoot) {
+async function maybeRunSetupWizard(projectRoot, workflowFile) {
   const root = projectRoot ?? await findProjectRoot();
-  if (await Bun.file(workflowPath(root)).exists())
+  if (await Bun.file(workflowPath(root, workflowFile)).exists())
     return false;
   if (!process.stdin.isTTY || !process.stdout.isTTY)
     return false;
-  return runSetupWizard(root);
+  const detected = await detectInitialValues(root);
+  return runSetupWizard(root, {
+    trackBackup: true,
+    ...workflowFile ? { workflowFile } : {},
+    ...Object.keys(detected).length > 0 ? { initialValues: detected } : {}
+  });
 }
 function initialValuesFromConfig(config2) {
   const values2 = {};
@@ -84149,8 +84697,16 @@ function initialValuesFromConfig(config2) {
   values2["useWorktree"] = config2.useWorktree;
   if (config2.linear.team)
     values2["linear.team"] = config2.linear.team;
-  if (config2.linear.filter)
-    values2["linear.filter"] = config2.linear.filter;
+  if (config2.linear.filter) {
+    const match = /^assignee\s*=\s*(.+)$/i.exec(config2.linear.filter.trim());
+    const assignee = match ? match[1].trim() : "";
+    if (assignee === "me" || assignee === "any" || assignee === "unassigned") {
+      values2["linear.assigneeChoice"] = assignee;
+    } else if (assignee !== "") {
+      values2["linear.assigneeChoice"] = "other";
+      values2["linear.assigneeValue"] = assignee;
+    }
+  }
   return values2;
 }
 async function promptEditOrExit() {
@@ -84164,6 +84720,17 @@ async function promptEditOrExit() {
   await waitUntilExit();
   return choice;
 }
+async function promptResumeOrFresh() {
+  let choice = "fresh";
+  clearScreen2();
+  const { waitUntilExit } = render_default(import_react23.createElement(ResumeOrFreshPrompt, {
+    onChoice: (value) => {
+      choice = value;
+    }
+  }));
+  await waitUntilExit();
+  return choice;
+}
 async function promptRecreateOrExit() {
   let choice = "exit";
   clearScreen2();
@@ -84189,14 +84756,16 @@ async function promptMigrate(fromVersion) {
   await waitUntilExit();
   return choice;
 }
-async function editExisting(projectRoot, path, config2, onlyFields) {
+async function editExisting(projectRoot, path, config2, workflowFile, onlyFields) {
   const existing = await Bun.file(path).text();
   const detectedRepo = await detectRepoIdentity(projectRoot);
+  const detected = await detectInitialValues(projectRoot);
   const wrote = await runSetupWizard(projectRoot, {
     existing,
     initialMode: "customized",
-    initialValues: initialValuesFromConfig(config2),
+    initialValues: { ...detected, ...initialValuesFromConfig(config2) },
     ...detectedRepo ? { detectedRepo } : {},
+    ...workflowFile ? { workflowFile } : {},
     ...onlyFields ? { onlyFields } : {}
   });
   process.stdout.write(wrote ? `
@@ -84212,8 +84781,9 @@ async function main(argv) {
 `);
     return 0;
   }
-  const projectRoot = await findProjectRoot();
-  const path = workflowPath(projectRoot);
+  const { projectRoot: rootOverride, workflowFile } = parseWorkflowPathArgs(argv);
+  const projectRoot = rootOverride ?? await findProjectRoot();
+  const path = workflowPath(projectRoot, workflowFile);
   const exists2 = await Bun.file(path).exists();
   const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
   if (exists2) {
@@ -84224,7 +84794,7 @@ async function main(argv) {
     }
     let config2;
     try {
-      ({ config: config2 } = await loadWorkflow(projectRoot));
+      ({ config: config2 } = await loadWorkflow(projectRoot, workflowFile));
     } catch {
       const choice2 = await promptRecreateOrExit();
       if (choice2 === "exit") {
@@ -84233,7 +84803,10 @@ async function main(argv) {
         return 0;
       }
       const detectedRepo2 = await detectRepoIdentity(projectRoot);
-      const wrote2 = await runSetupWizard(projectRoot, detectedRepo2 ? { detectedRepo: detectedRepo2 } : {});
+      const wrote2 = await runSetupWizard(projectRoot, {
+        ...detectedRepo2 ? { detectedRepo: detectedRepo2 } : {},
+        ...workflowFile ? { workflowFile } : {}
+      });
       process.stdout.write(wrote2 ? `
 \u2713 Recreated ${path}
 ` : `
@@ -84249,7 +84822,7 @@ Setup cancelled \u2014 no file written.
         return 0;
       }
       const onlyFields = choice2 === "diff" ? fieldsAddedSince(config2.version) : undefined;
-      return editExisting(projectRoot, path, config2, onlyFields);
+      return editExisting(projectRoot, path, config2, workflowFile, onlyFields);
     }
     const choice = await promptEditOrExit();
     if (choice === "exit") {
@@ -84257,17 +84830,42 @@ Setup cancelled \u2014 no file written.
 `);
       return 0;
     }
-    return editExisting(projectRoot, path, config2);
+    return editExisting(projectRoot, path, config2, workflowFile);
   }
   if (!interactive) {
     const { ensureWorkflow: ensureWorkflow2 } = await Promise.resolve().then(() => (init_workflow(), exports_workflow));
-    const written = await ensureWorkflow2(projectRoot);
+    const written = await ensureWorkflow2(projectRoot, workflowFile);
     process.stdout.write(`Non-interactive shell \u2014 wrote default WORKFLOW.md: ${written}
 `);
     return 0;
   }
+  const backup = await readSetupBackup(projectRoot);
+  if (backup) {
+    const choice = await promptResumeOrFresh();
+    if (choice === "resume") {
+      const wrote2 = await runSetupWizard(projectRoot, {
+        initialMode: backup.mode,
+        resumeValues: backup.values,
+        trackBackup: true,
+        ...workflowFile ? { workflowFile } : {}
+      });
+      process.stdout.write(wrote2 ? `
+\u2713 Created ${path}
+` : `
+Setup cancelled \u2014 no file written.
+`);
+      return 0;
+    }
+    await clearSetupBackup();
+  }
   const detectedRepo = await detectRepoIdentity(projectRoot);
-  const wrote = await runSetupWizard(projectRoot, detectedRepo ? { detectedRepo } : {});
+  const detected = await detectInitialValues(projectRoot);
+  const wrote = await runSetupWizard(projectRoot, {
+    trackBackup: true,
+    ...detectedRepo ? { detectedRepo } : {},
+    ...workflowFile ? { workflowFile } : {},
+    ...Object.keys(detected).length > 0 ? { initialValues: detected } : {}
+  });
   process.stdout.write(wrote ? `
 \u2713 Created ${path}
 ` : `
@@ -84278,10 +84876,12 @@ Setup cancelled \u2014 no file written.
 var import_react23, INIT_HELP;
 var init_src4 = __esm(async () => {
   init_paths();
+  init_common_args();
   init_workflow();
   init_wizard();
   init_repo();
   init_migrations();
+  init_project_detect();
   await __promiseAll([
     init_build2(),
     init_SetupWizard()
@@ -84290,10 +84890,15 @@ var init_src4 = __esm(async () => {
   INIT_HELP = [
     "ralphy init \u2014 create or edit WORKFLOW.md with an interactive setup wizard",
     "",
-    "Usage: ralphy init",
+    "Usage: ralphy init [options]",
     "",
     "Runs a short wizard (quick / permissive / customized) and writes WORKFLOW.md",
-    "to the project root. If WORKFLOW.md already exists, offers to edit it."
+    "to the project root. If WORKFLOW.md already exists, offers to edit it.",
+    "",
+    "Options:",
+    "  --project-root <path>   Directory to treat as the project root (default: detected)",
+    "  --workflow <path>       Path to read / write WORKFLOW.md (default: <project>/WORKFLOW.md)",
+    "  --help, -h              Show this help message"
   ].join(`
 `);
 });
@@ -84362,6 +84967,12 @@ function getLayout() {
     throw new Error("No layout in context. Set layout when calling runWithContext().");
   return ctx.layout;
 }
+function getArgs() {
+  const ctx = getContext();
+  if (!ctx.args)
+    throw new Error("No args in context. Set args when calling runWithContext().");
+  return ctx.args;
+}
 function runWithContext(ctx, fn) {
   return contextStore.run(ctx, fn);
 }
@@ -84374,18 +84985,18 @@ var init_context = __esm(() => {
 });
 
 // packages/core/src/layout.ts
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 function projectLayout(root) {
-  const statesDir = join6(root, ".ralph", "tasks");
-  const tasksDir = join6(root, "openspec", "changes");
+  const statesDir = join7(root, ".ralph", "tasks");
+  const tasksDir = join7(root, "openspec", "changes");
   return {
     root,
     statesDir,
     tasksDir,
-    agentStateFile: join6(root, ".ralph", "agent-state.json"),
-    changeDir: (name) => join6(tasksDir, name),
-    taskStateDir: (name) => join6(statesDir, name),
-    stateFile: (name) => join6(statesDir, name, STATE_FILE)
+    agentStateFile: join7(root, ".ralph", "agent-state.json"),
+    changeDir: (name) => join7(tasksDir, name),
+    taskStateDir: (name) => join7(statesDir, name),
+    stateFile: (name) => join7(statesDir, name, STATE_FILE)
   };
 }
 var STATE_FILE = ".ralph-state.json", GAVEUP_COUNT_FILE = ".ralph-gaveup-count";
@@ -84394,13 +85005,13 @@ var init_layout = __esm(() => {
 });
 
 // packages/openspec/src/openspec-bin.ts
-import { dirname as dirname3, join as join7 } from "path";
+import { dirname as dirname3, join as join8 } from "path";
 function findPackageRoot(startDir) {
   let dir = startDir;
   for (let i = 0;i < 8; i++) {
-    if (Bun.file(join7(dir, "package.json")).size >= 0) {
+    if (Bun.file(join8(dir, "package.json")).size >= 0) {
       try {
-        if (Bun.file(join7(dir, "package.json")).size > 0)
+        if (Bun.file(join8(dir, "package.json")).size > 0)
           return dir;
       } catch {}
     }
@@ -84436,11 +85047,11 @@ function ensureOpenspecInstalled(fromDir, runner) {
 function resolveOpenspecBin(fromDir, runner = bunInstallRunner) {
   try {
     const pkgJsonPath = runner.resolveSync("@fission-ai/openspec/package.json", fromDir);
-    return join7(dirname3(pkgJsonPath), "bin", "openspec.js");
+    return join8(dirname3(pkgJsonPath), "bin", "openspec.js");
   } catch {
     ensureOpenspecInstalled(fromDir, runner);
     const pkgJsonPath = runner.resolveSync("@fission-ai/openspec/package.json", fromDir);
-    return join7(dirname3(pkgJsonPath), "bin", "openspec.js");
+    return join8(dirname3(pkgJsonPath), "bin", "openspec.js");
   }
 }
 var bunInstallRunner;
@@ -84462,7 +85073,7 @@ var init_openspec_bin = __esm(() => {
 });
 
 // packages/openspec/src/openspec-change-store.ts
-import { dirname as dirname4, join as join8 } from "path";
+import { dirname as dirname4, join as join9 } from "path";
 import { readdir, mkdir as mkdir2 } from "fs/promises";
 function runOpenspec(args, options = {}) {
   const stdio = options.inherit ? ["inherit", "inherit", "inherit"] : ["ignore", "pipe", "pipe"];
@@ -84532,7 +85143,7 @@ class OpenSpecChangeStore {
     }
   }
   getChangeDirectory(name) {
-    return join8("openspec", "changes", name);
+    return join9("openspec", "changes", name);
   }
   async listChanges() {
     const result2 = runOpenspec(["list", "--json"]);
@@ -84546,7 +85157,7 @@ class OpenSpecChangeStore {
         }
       } catch {}
     }
-    const changesDir = join8("openspec", "changes");
+    const changesDir = join9("openspec", "changes");
     try {
       const entries = await readdir(changesDir, { withFileTypes: true });
       return entries.filter((entry) => entry.isDirectory() && entry.name !== "archive").map((entry) => entry.name);
@@ -84555,18 +85166,18 @@ class OpenSpecChangeStore {
     }
   }
   async readTaskList(name) {
-    const file2 = Bun.file(join8("openspec", "changes", name, "tasks.md"));
+    const file2 = Bun.file(join9("openspec", "changes", name, "tasks.md"));
     if (!await file2.exists())
       return "";
     return await file2.text();
   }
   async writeTaskList(name, content) {
-    const path = join8("openspec", "changes", name, "tasks.md");
+    const path = join9("openspec", "changes", name, "tasks.md");
     await mkdir2(dirname4(path), { recursive: true });
     await Bun.write(path, content);
   }
   async appendSteering(name, message) {
-    const path = join8("openspec", "changes", name, "steering.md");
+    const path = join9("openspec", "changes", name, "steering.md");
     const file2 = Bun.file(path);
     const existing = await file2.exists() ? await file2.text() : null;
     const updated = existing ? `${message}
@@ -84578,7 +85189,7 @@ ${existing.trimStart()}` : `${message}
     const firstLine = message.split(/\r?\n/).map((l) => l.trim()).find((l) => l.length > 0) ?? message.trim();
     if (firstLine.length === 0)
       return;
-    const tasksPath = join8("openspec", "changes", name, "tasks.md");
+    const tasksPath = join9("openspec", "changes", name, "tasks.md");
     const tasksFile = Bun.file(tasksPath);
     const existingTasks = await tasksFile.exists() ? await tasksFile.text() : "";
     const taskLine = `- [ ] Address steering: ${firstLine}`;
@@ -84711,171 +85322,6 @@ var init_output2 = __esm(() => {
   };
 });
 
-// packages/cli-args/src/common-args.ts
-function initialCommonArgs() {
-  return {
-    engine: "claude",
-    model: "opus",
-    engineSet: false,
-    maxIterations: 0,
-    maxCostUsd: 0,
-    maxRuntimeMinutes: 0,
-    maxConsecutiveFailures: 5,
-    delay: 0,
-    log: false,
-    verbose: false,
-    projectRoot: undefined,
-    name: "",
-    prompt: "",
-    fromAgent: false
-  };
-}
-function applyValueOption(option, args, raw) {
-  const setter = VALUE_SETTERS[option.argKey];
-  if (!setter)
-    throw new Error("no value setter registered for CLI option");
-  setter(args, raw);
-}
-function applyBooleanOption(option, args) {
-  const setter = BOOLEAN_SETTERS[option.argKey];
-  if (!setter)
-    throw new Error("no boolean setter registered for CLI option");
-  setter(args);
-}
-function emptyParseState() {
-  return {
-    pendingOption: null,
-    expectClaudeModel: false,
-    expectProjectRoot: false,
-    expectName: false,
-    expectPrompt: false,
-    expectPromptFile: false,
-    promptFilePath: null
-  };
-}
-function parseCommonArg(arg, args, state) {
-  if (state.pendingOption) {
-    applyValueOption(state.pendingOption, args, arg);
-    state.pendingOption = null;
-    return true;
-  }
-  if (state.expectClaudeModel) {
-    state.expectClaudeModel = false;
-    if (VALID_MODELS.has(arg)) {
-      args.model = arg;
-      return true;
-    }
-  }
-  if (state.expectProjectRoot) {
-    args.projectRoot = arg;
-    state.expectProjectRoot = false;
-    return true;
-  }
-  if (state.expectName) {
-    args.name = arg;
-    state.expectName = false;
-    return true;
-  }
-  if (state.expectPrompt) {
-    args.prompt = arg;
-    state.promptFilePath = null;
-    state.expectPrompt = false;
-    return true;
-  }
-  if (state.expectPromptFile) {
-    state.promptFilePath = arg;
-    state.expectPromptFile = false;
-    return true;
-  }
-  const option = OPTION_BY_FLAG.get(arg);
-  if (option) {
-    if (option.kind === "boolean")
-      applyBooleanOption(option, args);
-    else
-      state.pendingOption = option;
-    return true;
-  }
-  switch (arg) {
-    case "--claude":
-      if (args.engineSet && args.engine !== "claude") {
-        throw new Error("Choose only one engine flag: --claude or --codex");
-      }
-      args.engine = "claude";
-      args.engineSet = true;
-      state.expectClaudeModel = true;
-      return true;
-    case "--codex":
-      if (args.engineSet && args.engine !== "codex") {
-        throw new Error("Choose only one engine flag: --claude or --codex");
-      }
-      args.engine = "codex";
-      args.engineSet = true;
-      return true;
-    case "--unlimited":
-      args.maxIterations = 0;
-      return true;
-    case "--project-root":
-      state.expectProjectRoot = true;
-      return true;
-    case "--name":
-      state.expectName = true;
-      return true;
-    case "--prompt":
-      state.expectPrompt = true;
-      return true;
-    case "--prompt-file":
-      state.expectPromptFile = true;
-      return true;
-    case "--from-agent":
-      args.fromAgent = true;
-      return true;
-    default:
-      return false;
-  }
-}
-async function resolvePromptFile(args, state) {
-  if (state.promptFilePath !== null) {
-    args.prompt = await Bun.file(state.promptFilePath).text();
-  }
-}
-var VALID_MODELS, OPTION_BY_FLAG, VALUE_FLAGS, VALUE_SETTERS, BOOLEAN_SETTERS;
-var init_common_args = __esm(() => {
-  init_fields();
-  VALID_MODELS = new Set(modelOptionValues());
-  OPTION_BY_FLAG = new Map(COMMON_CLI_OPTIONS.map((option) => [option.flag, option]));
-  VALUE_FLAGS = new Set(COMMON_CLI_OPTIONS.filter((option) => option.kind !== "boolean").map((option) => option.flag));
-  VALUE_SETTERS = {
-    model: (args, raw) => {
-      if (!VALID_MODELS.has(raw))
-        throw new Error("Invalid model");
-      args.model = raw;
-    },
-    delay: (args, raw) => {
-      args.delay = parseInt(raw, 10);
-    },
-    maxCostUsd: (args, raw) => {
-      args.maxCostUsd = parseFloat(raw);
-    },
-    maxRuntimeMinutes: (args, raw) => {
-      args.maxRuntimeMinutes = parseFloat(raw);
-    },
-    maxConsecutiveFailures: (args, raw) => {
-      args.maxConsecutiveFailures = parseInt(raw, 10);
-    },
-    maxIterations: (args, raw) => {
-      args.maxIterations = parseInt(raw, 10);
-    }
-  };
-  BOOLEAN_SETTERS = {
-    log: (args) => {
-      args.log = true;
-    },
-    verbose: (args) => {
-      args.verbose = true;
-    }
-  };
-});
-
 // apps/loop/src/cli.ts
 function printLoopHelp() {
   log(HELP_TEXT);
@@ -84944,6 +85390,7 @@ async function parseLoopArgs(argv) {
     }
   }
   await resolvePromptFile(result2, state);
+  resolveWorkflowFile(result2, state);
   return result2;
 }
 var VALID_MODES, HELP_TEXT;
@@ -84966,6 +85413,7 @@ var init_cli = __esm(() => {
     "",
     "Options:",
     "  --name <name>           Change name (required for most commands)",
+    "  --workflow <path>       Path to an alternate WORKFLOW.md (default: <project>/WORKFLOW.md)",
     "  --prompt <text>         Task description",
     "  --prompt-file <path>    Read prompt from file",
     "  --model <model>         Set model (haiku|sonnet|opus)",
@@ -85022,6 +85470,7 @@ async function parseTaskArgs(argv) {
     }
   }
   await resolvePromptFile(result2, state);
+  resolveWorkflowFile(result2, state);
   if (!phaseSet) {
     throw new Error(`Missing phase. Valid phases: research, plan, execute, review. Run 'ralphy task --help' for usage information.`);
   }
@@ -85049,6 +85498,7 @@ var init_task_cli = __esm(() => {
     "",
     "Options:",
     "  --name <name>           Change name (required)",
+    "  --workflow <path>       Path to an alternate WORKFLOW.md (default: <project>/WORKFLOW.md)",
     "  --prompt <text>         Task description",
     "  --prompt-file <path>    Read prompt from file",
     "  --model <model>         Set model (haiku|sonnet|opus)",
@@ -85088,10 +85538,10 @@ var init_schema2 = __esm(() => {
 });
 
 // packages/core/src/state/sidecar.ts
-import { dirname as dirname5, join as join9 } from "path";
+import { dirname as dirname5, join as join10 } from "path";
 import { mkdir as mkdir3, rename, unlink } from "fs/promises";
 function slotSidecarPath(changeDir, slot) {
-  return join9(changeDir, `${CORE_STATE_FILE.replace(/\.json$/, "")}.${slot}.json`);
+  return join10(changeDir, `${CORE_STATE_FILE.replace(/\.json$/, "")}.${slot}.json`);
 }
 function parseObject(text) {
   if (text === null)
@@ -89273,7 +89723,7 @@ function formatTaskName(name) {
 }
 
 // packages/core/src/state.ts
-import { join as join10 } from "path";
+import { join as join11 } from "path";
 function stripOwnedSlots(state) {
   const out = { ...state };
   for (const slot of ALL_OWNED_SLOTS)
@@ -89281,7 +89731,7 @@ function stripOwnedSlots(state) {
   return out;
 }
 function readState(changeDir) {
-  const filePath = join10(changeDir, STATE_FILE2);
+  const filePath = join11(changeDir, STATE_FILE2);
   const raw = getStorage().read(filePath);
   if (raw === null)
     throw new Error(".ralph-state.json not found");
@@ -89290,7 +89740,7 @@ function readState(changeDir) {
   return StateSchema.parse(base2);
 }
 function tryReadStateRaw(changeDir) {
-  const filePath = join10(changeDir, STATE_FILE2);
+  const filePath = join11(changeDir, STATE_FILE2);
   const text = getStorage().read(filePath);
   if (text === null)
     return { state: null, raw: null };
@@ -89306,7 +89756,7 @@ function tryReadStateRaw(changeDir) {
   return { state: result2.success ? result2.data : null, raw };
 }
 function writeState(changeDir, state) {
-  const filePath = join10(changeDir, STATE_FILE2);
+  const filePath = join11(changeDir, STATE_FILE2);
   const core2 = stripOwnedSlots(state);
   getStorage().write(filePath, JSON.stringify(core2, null, 2) + `
 `);
@@ -89347,7 +89797,7 @@ function buildInitialState(options) {
   });
 }
 function ensureState(changeDir) {
-  const filePath = join10(changeDir, STATE_FILE2);
+  const filePath = join11(changeDir, STATE_FILE2);
   const storage = getStorage();
   if (storage.read(filePath) !== null) {
     return readState(changeDir);
@@ -89366,7 +89816,7 @@ var init_state = __esm(() => {
 });
 
 // packages/core/src/state/store.ts
-import { join as join11 } from "path";
+import { join as join12 } from "path";
 async function readJson(filePath) {
   const file2 = Bun.file(filePath);
   if (!await file2.exists())
@@ -89390,7 +89840,7 @@ async function writeField(changeDir, featureName, path, value) {
   if (!allowed.includes(topSlot)) {
     throw new OwnershipError(featureName, path, `feature '${featureName}' may not write '${path}' (owns ${allowed.join(", ")})`);
   }
-  const inline = (await readJson(join11(changeDir, STATE_FILE3)))[topSlot];
+  const inline = (await readJson(join12(changeDir, STATE_FILE3)))[topSlot];
   const seed = inline && typeof inline === "object" && !Array.isArray(inline) ? inline : undefined;
   await writeSlotField(changeDir, path, value, seed);
 }
@@ -89413,14 +89863,14 @@ var init_store = __esm(() => {
 });
 
 // apps/loop/src/components/TaskStatus.tsx
-import { join as join12 } from "path";
+import { join as join13 } from "path";
 function TaskStatus({ state, stateDir }) {
   const storage = getStorage();
   const cost = Math.round(state.usage.total_cost_usd * 100) / 100;
   const time3 = Math.round(state.usage.total_duration_ms / 1000 * 10) / 10 + "s";
   const artifacts = OPENSPEC_ARTIFACTS.map((name) => ({
     name,
-    exists: storage.read(join12(stateDir, name)) !== null
+    exists: storage.read(join13(stateDir, name)) !== null
   }));
   const recent = state.history.slice(-10);
   return /* @__PURE__ */ jsx_dev_runtime2.jsxDEV(Box_default, {
@@ -97382,10 +97832,10 @@ var require_xstate_development_cjs = __commonJS((exports) => {
     }
   }
   function toPromise(actor) {
-    return new Promise((resolve3, reject2) => {
+    return new Promise((resolve4, reject2) => {
       actor.subscribe({
         complete: () => {
-          resolve3(actor.getSnapshot().output);
+          resolve4(actor.getSnapshot().output);
         },
         error: reject2
       });
@@ -98138,7 +98588,7 @@ var init_rate_limit_detection = __esm(() => {
 
 // packages/engine/src/agents/claude.ts
 import { mkdtemp, unlink as unlink2 } from "fs/promises";
-import { join as join13 } from "path";
+import { join as join14 } from "path";
 import { tmpdir } from "os";
 function buildClaudeArgs(model, resumeSessionId, reviewerContextStrategy, reviewerModel) {
   const effectiveModel = reviewerModel ?? model;
@@ -98159,7 +98609,7 @@ function buildClaudeArgs(model, resumeSessionId, reviewerContextStrategy, review
 }
 async function runInteractive(req) {
   const { model, prompt, taskDir } = req;
-  const promptFile = taskDir ? join13(taskDir, "_interactive_prompt.md") : join13(await mkdtemp(join13(tmpdir(), "ralph-")), "prompt.md");
+  const promptFile = taskDir ? join14(taskDir, "_interactive_prompt.md") : join14(await mkdtemp(join14(tmpdir(), "ralph-")), "prompt.md");
   await Bun.write(promptFile, prompt);
   try {
     const cmd = [
@@ -98186,7 +98636,7 @@ async function runInteractive(req) {
       env: scrubClaudeEnv(process.env)
     });
     const exitCode = await proc.exited;
-    const doneFile = taskDir ? join13(taskDir, "_interactive_done") : null;
+    const doneFile = taskDir ? join14(taskDir, "_interactive_done") : null;
     if (doneFile && await Bun.file(doneFile).exists()) {
       return { exitCode: 0, usage: null, sessionId: null, rateLimited: false };
     }
@@ -98816,10 +99266,10 @@ async function runEngine(opts) {
     await mkdir4(dirname6(opts.logFile), { recursive: true });
     rawWriter = createWriteStream(opts.logFile, { flags: "a" });
   }
-  const closeRaw = () => new Promise((resolve3) => {
+  const closeRaw = () => new Promise((resolve4) => {
     if (!rawWriter)
-      return resolve3();
-    rawWriter.end(resolve3);
+      return resolve4();
+    rawWriter.end(resolve4);
   });
   const userOnFeedEvent = opts.onFeedEvent;
   const onFeedEvent = (event) => {
@@ -98963,8 +99413,8 @@ var init_flow_machine = __esm(() => {
       } catch {}
       const exited = await Promise.race([
         worker.exited.then(() => "exited"),
-        new Promise((resolve3) => {
-          const t = setTimeout(() => resolve3("timeout"), graceMs);
+        new Promise((resolve4) => {
+          const t = setTimeout(() => resolve4("timeout"), graceMs);
           t.unref();
         })
       ]);
@@ -99689,11 +100139,11 @@ var init_meta_prompt = __esm(() => {
 });
 
 // packages/core/src/loop.ts
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 function buildTaskPrompt(state, taskDir, reviewPhase) {
   const storage = getStorage();
   let prompt = "";
-  const steeringContent = storage.read(join14(taskDir, "steering.md"));
+  const steeringContent = storage.read(join15(taskDir, "steering.md"));
   if (steeringContent !== null) {
     const steeringLines = steeringContent.split(`
 `).filter((line) => !line.startsWith("#")).filter((line) => line.trim()).slice(0, STEERING_MAX_LINES);
@@ -99712,8 +100162,8 @@ function buildTaskPrompt(state, taskDir, reviewPhase) {
 `;
     }
   }
-  const agentTasksPath = join14(taskDir, AGENT_TASKS_FILENAME);
-  const missionTasksPath = join14(taskDir, MISSION_TASKS_FILENAME);
+  const agentTasksPath = join15(taskDir, AGENT_TASKS_FILENAME);
+  const missionTasksPath = join15(taskDir, MISSION_TASKS_FILENAME);
   const agentTasksContent = storage.read(agentTasksPath);
   const missionTasksContent = storage.read(missionTasksPath);
   let activePath = null;
@@ -99789,7 +100239,7 @@ function buildTaskPrompt(state, taskDir, reviewPhase) {
     }
   }
   if (reviewPhase?.enabled) {
-    const reviewFindingsPath = join14(taskDir, "review-findings.md");
+    const reviewFindingsPath = join15(taskDir, "review-findings.md");
     const reviewFindingsContent = storage.read(reviewFindingsPath);
     const hasUncheckedMission = missionTasksContent !== null && /^- \[ \]/m.test(missionTasksContent);
     const hasUncheckedAgent = agentTasksContent !== null && /^- \[ \]/m.test(agentTasksContent);
@@ -99863,7 +100313,7 @@ When all tasks are complete and all files are committed, push your branch and op
 }
 function buildSteeringBlock(taskDir) {
   const storage = getStorage();
-  const steeringContent = storage.read(join14(taskDir, "steering.md"));
+  const steeringContent = storage.read(join15(taskDir, "steering.md"));
   if (steeringContent === null)
     return "";
   const steeringLines = steeringContent.split(`
@@ -99961,7 +100411,7 @@ function buildPlanPrompt(state, taskDir) {
   return prompt;
 }
 function buildReviewPrompt(state, taskDir) {
-  const reviewFindingsPath = join14(taskDir, "review-findings.md");
+  const reviewFindingsPath = join15(taskDir, "review-findings.md");
   let prompt = buildSteeringBlock(taskDir);
   prompt += `---
 
@@ -100026,7 +100476,7 @@ function buildPhasePrompt(phase, state, taskDir, reviewPhase, metaPromptOptions)
 }
 function checkStopSignal(taskDir, stateDir) {
   const storage = getStorage();
-  const stopFile = join14(taskDir, "STOP");
+  const stopFile = join15(taskDir, "STOP");
   const reason = storage.read(stopFile);
   if (reason === null)
     return null;
@@ -100086,7 +100536,7 @@ function updateStateIteration(stateDir, result2, startedAt, engine, model, usage
 }
 function appendSteeringMessage(taskDir, message) {
   const storage = getStorage();
-  const steeringPath = join14(taskDir, "steering.md");
+  const steeringPath = join15(taskDir, "steering.md");
   const existing = storage.read(steeringPath);
   const updated = existing ? `${message}
 
@@ -100136,9 +100586,9 @@ var init_loop2 = __esm(() => {
 });
 
 // apps/loop/src/hooks/useLoop.ts
-import { join as join15 } from "path";
+import { join as join16 } from "path";
 function sleep(seconds) {
-  return new Promise((resolve3) => setTimeout(resolve3, seconds * 1000));
+  return new Promise((resolve4) => setTimeout(resolve4, seconds * 1000));
 }
 function useLoop(opts) {
   const outerLayoutRef = import_react57.useRef(null);
@@ -100252,8 +100702,8 @@ function useLoop(opts) {
         setState(currentState);
         if (!actor.getSnapshot().matches("running"))
           break;
-        const tasksContent = storage.read(join15(tasksDir, MISSION_TASKS_FILENAME));
-        const agentTasksContent = storage.read(join15(tasksDir, AGENT_TASKS_FILENAME));
+        const tasksContent = storage.read(join16(tasksDir, MISSION_TASKS_FILENAME));
+        const agentTasksContent = storage.read(join16(tasksDir, AGENT_TASKS_FILENAME));
         if (tasksContent === null && currentState.iteration > 0 && typeof opts.changeStore.listChanges === "function") {
           let stillActive = true;
           try {
@@ -100290,7 +100740,7 @@ function useLoop(opts) {
         const agentDone = agentTasksContent === null || allCompleted(agentTasksContent);
         if (missionDone && agentDone && tasksContent !== null) {
           if (opts.reviewPhase?.enabled) {
-            const reviewFindingsPath = join15(tasksDir, "review-findings.md");
+            const reviewFindingsPath = join16(tasksDir, "review-findings.md");
             const reviewFindingsFile = Bun.file(reviewFindingsPath);
             const findingsExists = await reviewFindingsFile.exists();
             const findingsContent = findingsExists ? await reviewFindingsFile.text() : null;
@@ -100319,7 +100769,7 @@ function useLoop(opts) {
                 model: opts.reviewPhase.reviewerModel ?? opts.model,
                 prompt: reviewPrompt,
                 logFlag: opts.log,
-                logFile: join15(stateDir, `log-review-${roundNum}.json`),
+                logFile: join16(stateDir, `log-review-${roundNum}.json`),
                 taskDir: tasksDir,
                 reviewerContextStrategy: opts.reviewPhase.reviewerContextStrategy ?? "fresh",
                 onFeedEvent: addFeedEvent
@@ -100393,8 +100843,8 @@ function useLoop(opts) {
         const time3 = new Date().toLocaleTimeString("en-US", { hour12: false });
         addIterationHeader(localIter, time3);
         addInfo(`Iteration ${localIter} (total: ${currentState.iteration})`);
-        const proposalContent = storage.read(join15(tasksDir, "proposal.md"));
-        const designContent = storage.read(join15(tasksDir, "design.md"));
+        const proposalContent = storage.read(join16(tasksDir, "proposal.md"));
+        const designContent = storage.read(join16(tasksDir, "design.md"));
         const routedPhase = routeTaskPhase(opts.phase, {
           proposal: proposalContent,
           design: designContent,
@@ -100414,7 +100864,7 @@ function useLoop(opts) {
             model: opts.model,
             prompt,
             logFlag: opts.log,
-            logFile: join15(stateDir, "log.json"),
+            logFile: join16(stateDir, "log.json"),
             taskDir: tasksDir,
             interactive: false,
             onFeedEvent: addFeedEvent,
@@ -100437,7 +100887,7 @@ function useLoop(opts) {
               model: opts.model,
               prompt: buildSteeringPrompt(steerMessage),
               logFlag: opts.log,
-              logFile: join15(stateDir, "log.json"),
+              logFile: join16(stateDir, "log.json"),
               taskDir: tasksDir,
               onFeedEvent: addResumeFeedEvent,
               signal: resumeController.signal,
@@ -100744,7 +101194,7 @@ var init_TaskLoop = __esm(async () => {
 });
 
 // apps/loop/src/components/App.tsx
-import { join as join16 } from "path";
+import { join as join17 } from "path";
 function ExitAfterRender({ children }) {
   const { exit } = use_app_default();
   import_react59.useEffect(() => {
@@ -100797,7 +101247,7 @@ function App2({ args, taskPhase }) {
       }
       const layout = getLayout();
       const stateDir = layout.taskStateDir(args.name);
-      if (getStorage().read(join16(stateDir, ".ralph-state.json")) === null) {
+      if (getStorage().read(join17(stateDir, ".ralph-state.json")) === null) {
         return /* @__PURE__ */ jsx_dev_runtime9.jsxDEV(ErrorMessage, {
           message: `Error: change '${args.name}' not found`
         }, undefined, false, undefined, this);
@@ -100851,7 +101301,7 @@ var init_App2 = __esm(async () => {
 
 // packages/log/src/log.ts
 import { appendFile } from "fs/promises";
-import { join as join17, dirname as dirname7 } from "path";
+import { join as join18, dirname as dirname7 } from "path";
 import { homedir as homedir4 } from "os";
 import { mkdir as mkdir5 } from "fs/promises";
 function fmt(type, text) {
@@ -100900,14 +101350,14 @@ var init_log = __esm(() => {
   init_version();
   jsonLogChains = new Map;
   ANSI_RE = /\x1b(?:\[[0-9;]*[A-Za-z]|\][^\x07\x1b]*(?:\x07|\x1b\\)|.)/g;
-  AGENT_LOG_PATH = join17(homedir4(), ".ralph", "agent-mode.log");
+  AGENT_LOG_PATH = join18(homedir4(), ".ralph", "agent-mode.log");
   mkdir5(dirname7(AGENT_LOG_PATH), { recursive: true }).catch(() => {
     return;
   });
 });
 
 // apps/loop/src/debug.ts
-import { join as join18 } from "path";
+import { join as join19 } from "path";
 function fmtTs(d) {
   return d.toISOString().replace("T", " ").slice(0, 23);
 }
@@ -101019,7 +101469,7 @@ function detectDebugStuck(lines) {
   };
 }
 async function inspectBinary(projectRoot) {
-  const binPath = join18(projectRoot, ".ralph", "bin", "cli.js");
+  const binPath = join19(projectRoot, ".ralph", "bin", "cli.js");
   const file2 = Bun.file(binPath);
   if (!await file2.exists())
     return null;
@@ -101044,7 +101494,7 @@ async function inspectBinary(projectRoot) {
 async function resolveDebugTarget(projectRoot, opts) {
   const agentLogFile = Bun.file(AGENT_LOG_PATH);
   const textLines = await agentLogFile.exists() ? parseTextLog(await agentLogFile.text()) : [];
-  const jsonlLogFile = Bun.file(join18(projectRoot, ".ralph", "agent.log"));
+  const jsonlLogFile = Bun.file(join19(projectRoot, ".ralph", "agent.log"));
   const jsonlLines = await jsonlLogFile.exists() ? parseJsonlLog(await jsonlLogFile.text()) : [];
   const allLines = [...textLines, ...jsonlLines];
   if (opts.name && !opts.issue) {
@@ -101149,7 +101599,7 @@ async function runDebug(opts) {
 `);
   const agentLogFile = Bun.file(AGENT_LOG_PATH);
   const textLines = await agentLogFile.exists() ? parseTextLog(await agentLogFile.text()) : [];
-  const jsonlLogPath = join18(projectRoot, ".ralph", "agent.log");
+  const jsonlLogPath = join19(projectRoot, ".ralph", "agent.log");
   const jsonlLogFile = Bun.file(jsonlLogPath);
   const hasJsonlLog = await jsonlLogFile.exists();
   let { changeName, identifier: issueIdentifier } = await resolveDebugTarget(projectRoot, {
@@ -101163,7 +101613,7 @@ async function runDebug(opts) {
   }
   const jsonlLines = hasJsonlLog ? parseJsonlLog(await jsonlLogFile.text(), changeName) : [];
   const relevantText = textLines.filter((l) => l.text.includes(changeName) || issueIdentifier !== undefined && l.text.includes(issueIdentifier));
-  const workerLogFile = Bun.file(join18(projectRoot, ".ralph", "logs", `${changeName}.log`));
+  const workerLogFile = Bun.file(join19(projectRoot, ".ralph", "logs", `${changeName}.log`));
   const workerLines = await workerLogFile.exists() ? parseTextLog(await workerLogFile.text()) : [];
   const merged = [...relevantText, ...jsonlLines, ...workerLines].sort((a, b) => +a.ts - +b.ts);
   const seen = new Set;
@@ -101322,8 +101772,8 @@ async function runDebug(opts) {
     out("  \u26A0 PR currently has merge conflicts");
   if (pr?.checks.some((c) => c.conclusion === "FAILURE"))
     out("  \u26A0 PR has failing CI checks");
-  const worktreePath = join18(projectRoot, ".ralph", "worktrees", changeName);
-  if (await Bun.file(join18(worktreePath, ".git")).exists()) {
+  const worktreePath = join19(projectRoot, ".ralph", "worktrees", changeName);
+  if (await Bun.file(join19(worktreePath, ".git")).exists()) {
     out(`  Worktree   : ${worktreePath}`);
   }
   if (!timeline.length)
@@ -101343,12 +101793,12 @@ __export(exports_src2, {
   taskMain: () => taskMain,
   main: () => main2
 });
-import { join as join19 } from "path";
+import { join as join20 } from "path";
 import { exists as exists2, mkdir as mkdir6, rm as rm2 } from "fs/promises";
 async function ensureRalphGitignore(projectRoot) {
-  const ralphDir = join19(projectRoot, ".ralph");
+  const ralphDir = join20(projectRoot, ".ralph");
   await mkdir6(ralphDir, { recursive: true });
-  const gitignorePath = join19(ralphDir, ".gitignore");
+  const gitignorePath = join20(ralphDir, ".gitignore");
   const file2 = Bun.file(gitignorePath);
   if (await file2.exists()) {
     const existing = await file2.text();
@@ -101390,14 +101840,14 @@ async function main2(argv) {
     await mkdir6(statesDir, { recursive: true });
     await ensureRalphGitignore(projectRoot);
     const { ensureWorkflow: ensureWorkflow2 } = await Promise.resolve().then(() => (init_workflow(), exports_workflow));
-    const workflowPath2 = await ensureWorkflow2(projectRoot);
+    const workflowPath2 = await ensureWorkflow2(projectRoot, args.workflowFile);
     process.stdout.write(`Workflow config: ${workflowPath2}
 `);
     const openspecBin = resolveOpenspecBin(import.meta.dir);
     Bun.spawnSync({
       cmd: [process.execPath, openspecBin, "init", "--tools", "none", "--force"],
       stdio: ["inherit", "inherit", "inherit"],
-      cwd: process.cwd()
+      cwd: projectRoot
     });
   }
   if (args.mode === "debug") {
@@ -101415,9 +101865,9 @@ async function main2(argv) {
 `);
       return 1;
     }
-    const worktreeDir = join19(worktreesDir(projectRoot), args.name);
-    const changeDir = join19(tasksDir, args.name);
-    const stateDir = join19(statesDir, args.name);
+    const worktreeDir = join20(worktreesDir(projectRoot), args.name);
+    const changeDir = join20(tasksDir, args.name);
+    const stateDir = join20(statesDir, args.name);
     const branch = `ralph/${args.name}`;
     const removed = [];
     if (await exists2(worktreeDir)) {
@@ -101468,8 +101918,8 @@ async function main2(argv) {
     return 0;
   }
   if (args.mode === "task" && args.name) {
-    await mkdir6(join19(statesDir, args.name), { recursive: true });
-    await mkdir6(join19(tasksDir, args.name), { recursive: true });
+    await mkdir6(join20(statesDir, args.name), { recursive: true });
+    await mkdir6(join20(tasksDir, args.name), { recursive: true });
     await ensureRalphGitignore(projectRoot);
   }
   await runWithContext(createDefaultContext({ layout, args }), async () => {
@@ -101497,8 +101947,8 @@ async function taskMain(argv) {
   const layout = projectLayout(projectRoot);
   const statesDir = layout.statesDir;
   const tasksDir = layout.tasksDir;
-  await mkdir6(join19(statesDir, args.name), { recursive: true });
-  await mkdir6(join19(tasksDir, args.name), { recursive: true });
+  await mkdir6(join20(statesDir, args.name), { recursive: true });
+  await mkdir6(join20(tasksDir, args.name), { recursive: true });
   await ensureRalphGitignore(projectRoot);
   await runWithContext(createDefaultContext({ layout, args }), async () => {
     const { waitUntilExit } = render_default(import_react60.createElement(App2, {
@@ -101741,6 +102191,7 @@ async function parseAgentArgs(argv) {
     }
   }
   await resolvePromptFile(result2, state);
+  resolveWorkflowFile(result2, state);
   if (result2.fixCi && !result2.createPr) {
     throw new Error("--fix-ci requires --create-pr");
   }
@@ -101778,6 +102229,7 @@ var init_cli2 = __esm(() => {
     "",
     "Options:",
     "  --name <id>             Change name / ticket identifier (list / debug filter)",
+    "  --workflow <path>       Path to an alternate WORKFLOW.md (default: <project>/WORKFLOW.md)",
     "  --prompt <text>         Task description appended to every scaffolded proposal",
     "  --prompt-file <path>    Read prompt from file",
     "  --model <model>         Set model (haiku|sonnet|opus)",
@@ -101838,12 +102290,12 @@ __export(exports_config, {
   loadRalphyConfig: () => loadRalphyConfig,
   ensureRalphyConfig: () => ensureRalphyConfig
 });
-async function loadRalphyConfig(projectRoot) {
-  const { config: config2 } = await loadWorkflow(projectRoot);
+async function loadRalphyConfig(projectRoot, workflowFile) {
+  const { config: config2 } = await loadWorkflow(projectRoot, workflowFile);
   return config2;
 }
-async function ensureRalphyConfig(projectRoot) {
-  return ensureWorkflow(projectRoot);
+async function ensureRalphyConfig(projectRoot, workflowFile) {
+  return ensureWorkflow(projectRoot, workflowFile);
 }
 var init_config = __esm(() => {
   init_workflow();
@@ -101897,7 +102349,7 @@ function formatError2(err) {
 }
 
 // apps/agent/src/shared/capabilities/fs-change.ts
-import { join as join20, dirname as dirname8 } from "path";
+import { join as join21, dirname as dirname8 } from "path";
 import { mkdir as mkdir7 } from "fs/promises";
 var scaffold, prependTask, appendSteering, fsChange;
 var init_fs_change = __esm(() => {
@@ -101910,11 +102362,11 @@ var init_fs_change = __esm(() => {
     errorFormatter: formatError2,
     run: async (args) => {
       await mkdir7(args.changeDir, { recursive: true });
-      await mkdir7(join20(args.changeDir, "specs"), { recursive: true });
+      await mkdir7(join21(args.changeDir, "specs"), { recursive: true });
       await mkdir7(args.stateDir, { recursive: true });
-      await Bun.write(join20(args.changeDir, "proposal.md"), args.proposal);
-      await Bun.write(join20(args.changeDir, "tasks.md"), args.tasks);
-      await Bun.write(join20(args.changeDir, "design.md"), args.design);
+      await Bun.write(join21(args.changeDir, "proposal.md"), args.proposal);
+      await Bun.write(join21(args.changeDir, "tasks.md"), args.tasks);
+      await Bun.write(join21(args.changeDir, "design.md"), args.design);
     }
   };
   prependTask = {
@@ -101932,7 +102384,7 @@ var init_fs_change = __esm(() => {
     retryPolicy: NO_RETRY,
     errorFormatter: formatError2,
     run: async (args) => {
-      const path = join20(args.changeDir, "steering.md");
+      const path = join21(args.changeDir, "steering.md");
       const f2 = Bun.file(path);
       const existing = await f2.exists() ? await f2.text() : null;
       const updated = existing ? `${args.message}
@@ -101947,11 +102399,11 @@ ${existing.trimStart()}` : `${args.message}
 });
 
 // apps/agent/src/agent/worktree.ts
-import { basename as basename2, join as join21 } from "path";
+import { basename as basename2, join as join22 } from "path";
 import { homedir as homedir5 } from "os";
 import { exists as exists3 } from "fs/promises";
 function worktreesDir2(projectRoot) {
-  return join21(homedir5(), ".ralph", basename2(projectRoot), "worktrees");
+  return join22(homedir5(), ".ralph", basename2(projectRoot), "worktrees");
 }
 function branchForChange(changeName) {
   return `ralph/${changeName}`;
@@ -101970,7 +102422,7 @@ function createWorktree(projectRoot, changeName, baseBranch, runner) {
 }
 async function provisionWorktree(projectRoot, changeName, baseBranch, runner) {
   const dir = worktreesDir2(projectRoot);
-  const cwd2 = join21(dir, changeName);
+  const cwd2 = join22(dir, changeName);
   const branch = branchForChange(changeName);
   const list = await runner.run(["worktree", "list", "--porcelain"], projectRoot);
   if (list.stdout.includes(`worktree ${cwd2}
@@ -101995,7 +102447,7 @@ async function provisionWorktree(projectRoot, changeName, baseBranch, runner) {
   return { cwd: cwd2, branch };
 }
 async function installPrePushHook(cwd2, runner) {
-  const hookPath = join21(cwd2, ".ralph-hooks", "pre-push");
+  const hookPath = join22(cwd2, ".ralph-hooks", "pre-push");
   await Bun.write(hookPath, PRE_PUSH_HOOK_SCRIPT);
   const chmod = Bun.spawn(["chmod", "+x", hookPath]);
   await chmod.exited;
@@ -102041,8 +102493,8 @@ async function isWorktreeSafeToRemove(cwd2, base2, runner) {
   return { safe: true, dirty, unpushedCommits };
 }
 async function seedWorktreeMcpConfig(projectRoot, worktreeCwd) {
-  const dst = join21(worktreeCwd, ".mcp.json");
-  const src = join21(projectRoot, ".mcp.json");
+  const dst = join22(worktreeCwd, ".mcp.json");
+  const src = join22(projectRoot, ".mcp.json");
   const source = await exists3(dst) ? dst : await exists3(src) ? src : null;
   if (!source)
     return;
@@ -102056,7 +102508,7 @@ async function seedWorktreeMcpConfig(projectRoot, worktreeCwd) {
   if (servers && typeof servers === "object") {
     for (const cfg of Object.values(servers)) {
       if (Array.isArray(cfg.args)) {
-        cfg.args = cfg.args.map((a) => typeof a === "string" && a.startsWith(".ralph/") ? join21(projectRoot, a) : a);
+        cfg.args = cfg.args.map((a) => typeof a === "string" && a.startsWith(".ralph/") ? join22(projectRoot, a) : a);
       }
     }
   }
@@ -102150,7 +102602,7 @@ async function runCapability(cap, args, ctx = {}) {
   throw lastError;
 }
 function sleepMs(ms) {
-  return new Promise((resolve3) => setTimeout(resolve3, ms));
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
 
 // packages/workflow/src/boundaries.ts
@@ -103906,7 +104358,7 @@ function emitFeatureSkipped(bus, id, reason) {
 var init_run_feature = () => {};
 
 // apps/agent/src/agent/post-task.ts
-import { join as join22, dirname as dirname9 } from "path";
+import { join as join23, dirname as dirname9 } from "path";
 function summarizeUncommittedStatus(stdout) {
   const lines = stdout.split(`
 `).filter((line) => line.length > 0);
@@ -103978,7 +104430,7 @@ async function reactivateState(stateFilePath, log3, changeName) {
 async function runWorkerWithFixTask(ctx, heading, body) {
   try {
     await runCapability(fsChange.prependTask, {
-      tasksPath: join22(ctx.changeDir, AGENT_TASKS_FILENAME),
+      tasksPath: join23(ctx.changeDir, AGENT_TASKS_FILENAME),
       heading,
       failureOutput: body
     });
@@ -104529,7 +104981,7 @@ async function runValidateOnlyPhase(input, deps) {
         emit3("validate-fix", command);
         log3(`! validation check failed: ${command}`, "yellow");
         try {
-          await prependFixTask(join22(changeDir, AGENT_TASKS_FILENAME), `Fix failing validation: ${command}`, output || `Command exited with code ${exitCode}`);
+          await prependFixTask(join23(changeDir, AGENT_TASKS_FILENAME), `Fix failing validation: ${command}`, output || `Command exited with code ${exitCode}`);
         } catch (err) {
           log3(`! could not prepend fix task: ${err.message}`, "red");
           return 1;
@@ -104540,7 +104992,7 @@ async function runValidateOnlyPhase(input, deps) {
     }
   }
   try {
-    await prependFixTask(join22(changeDir, AGENT_TASKS_FILENAME), "Run openspec validation", [
+    await prependFixTask(join23(changeDir, AGENT_TASKS_FILENAME), "Run openspec validation", [
       `Run \`bunx openspec validate ${changeName}\` to validate the change artifacts.`,
       `Commit any pending changes before running the validation command.`
     ].join(`
@@ -104553,7 +105005,7 @@ async function runValidateOnlyPhase(input, deps) {
   return respawnWorker();
 }
 async function recordGaveUp(stateFilePath, log3, changeName) {
-  const path = join22(dirname9(stateFilePath), GAVEUP_COUNT_FILE);
+  const path = join23(dirname9(stateFilePath), GAVEUP_COUNT_FILE);
   try {
     const file2 = Bun.file(path);
     const current = await file2.exists() ? Number.parseInt(await file2.text(), 10) || 0 : 0;
@@ -105960,15 +106412,15 @@ var init_coordinator2 = __esm(() => {
 });
 
 // apps/agent/src/agent/scaffold.ts
-import { join as join23 } from "path";
+import { join as join24 } from "path";
 function changeNameForIssue(issue2) {
   const slug = issue2.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 40).replace(/^-+|-+$/g, "");
   return slug ? `${issue2.identifier.toLowerCase()}-${slug}` : issue2.identifier.toLowerCase();
 }
 async function scaffoldChangeForIssue(tasksDir, statesDir, issue2, comments = [], appendPrompt = "", attachments = []) {
   const name = changeNameForIssue(issue2);
-  const changeDir = join23(tasksDir, name);
-  const stateDir = join23(statesDir, name);
+  const changeDir = join24(tasksDir, name);
+  const stateDir = join24(statesDir, name);
   const commentsBlock = comments.length > 0 ? [
     "",
     "## Linear comments",
@@ -106104,7 +106556,7 @@ var init_detections = __esm(() => {
 });
 
 // apps/agent/src/features/confirmation/state.ts
-import { dirname as dirname10, join as join24 } from "path";
+import { dirname as dirname10, join as join25 } from "path";
 async function readInlineConfirmation(statePath) {
   const f2 = Bun.file(statePath);
   if (!await f2.exists())
@@ -106143,8 +106595,8 @@ async function restartFromDesign(changeDir, changeName) {
     ""
   ].join(`
 `);
-  await Bun.write(join24(changeDir, "design.md"), designStub);
-  const tasksPath = join24(changeDir, "tasks.md");
+  await Bun.write(join25(changeDir, "design.md"), designStub);
+  const tasksPath = join25(changeDir, "tasks.md");
   if (await Bun.file(tasksPath).exists()) {
     await Bun.write(tasksPath, `# Tasks
 
@@ -106374,7 +106826,7 @@ var init_inspect = __esm(() => {
 });
 
 // apps/agent/src/features/confirmation/awaiting.ts
-import { join as join25 } from "path";
+import { join as join26 } from "path";
 async function resolveChangeCwdForIssue(issue2, changeName, deps) {
   const tracked = deps.cwdOf(changeName);
   if (tracked)
@@ -106382,12 +106834,12 @@ async function resolveChangeCwdForIssue(issue2, changeName, deps) {
   if (!deps.useWorktree)
     return deps.projectRoot;
   const root = worktreesDir2(deps.projectRoot);
-  const canonical = join25(root, worktreeDirNameForIssue(issue2));
-  if (await Bun.file(join25(canonical, "openspec", "changes", changeName, "tasks.md")).exists()) {
+  const canonical = join26(root, worktreeDirNameForIssue(issue2));
+  if (await Bun.file(join26(canonical, "openspec", "changes", changeName, "tasks.md")).exists()) {
     return canonical;
   }
-  const legacy = join25(root, changeName);
-  if (await Bun.file(join25(legacy, "openspec", "changes", changeName, "tasks.md")).exists()) {
+  const legacy = join26(root, changeName);
+  if (await Bun.file(join26(legacy, "openspec", "changes", changeName, "tasks.md")).exists()) {
     return legacy;
   }
   return deps.projectRoot;
@@ -106522,9 +106974,9 @@ async function processAwaitingForIssue(issue2, deps) {
     const layout = projectLayout(cwd2);
     const changeDir = layout.changeDir(changeName);
     const statePath = layout.stateFile(changeName);
-    const tasks2 = await readTextOrNull(join25(changeDir, "tasks.md"));
-    const proposal = await readTextOrNull(join25(changeDir, "proposal.md"));
-    const design = await readTextOrNull(join25(changeDir, "design.md"));
+    const tasks2 = await readTextOrNull(join26(changeDir, "tasks.md"));
+    const proposal = await readTextOrNull(join26(changeDir, "proposal.md"));
+    const design = await readTextOrNull(join26(changeDir, "design.md"));
     let commentsCache = null;
     const getComments = async () => {
       if (commentsCache)
@@ -107068,7 +107520,7 @@ var init_linear_resolvers = __esm(() => {
 
 // apps/agent/src/agent/wire/prepare.ts
 import { mkdir as mkdir8 } from "fs/promises";
-import { join as join26 } from "path";
+import { join as join27 } from "path";
 function createPrepareHelpers(input) {
   const {
     args,
@@ -107132,7 +107584,7 @@ function createPrepareHelpers(input) {
     let changeName;
     const wtLayoutPre = projectLayout(workerCwd);
     const derivedName = changeNameForIssue(issue2);
-    const tasksMdPath = join26(wtLayoutPre.changeDir(derivedName), "tasks.md");
+    const tasksMdPath = join27(wtLayoutPre.changeDir(derivedName), "tasks.md");
     const tasksMdExists = await Bun.file(tasksMdPath).exists();
     const isFresh = !tasksMdExists;
     if (isFresh) {
@@ -107150,7 +107602,7 @@ function createPrepareHelpers(input) {
       }
       let workflowPrompt = "";
       try {
-        const workflow = await loadWorkflow(projectRoot);
+        const workflow = await loadWorkflow(projectRoot, args.workflowFile);
         workflowPrompt = renderWorkflowPrompt(workflow, {
           issue: {
             identifier: issue2.identifier,
@@ -107210,7 +107662,7 @@ function createPrepareHelpers(input) {
     if (!workerCwd)
       return;
     const wtLayout = projectLayout(workerCwd);
-    const tasksFile = join26(wtLayout.changeDir(changeName), AGENT_TASKS_FILENAME);
+    const tasksFile = join27(wtLayout.changeDir(changeName), AGENT_TASKS_FILENAME);
     if (trigger === "review") {
       let body2;
       let heading;
@@ -107503,14 +107955,14 @@ var init_pr_discovery = __esm(() => {
 });
 
 // apps/agent/src/features/review-followup/scan.ts
-import { dirname as dirname11, join as join27 } from "path";
+import { dirname as dirname11, join as join28 } from "path";
 async function resolveReviewStateDir(changeName, deps) {
   const root = deps.cwdOf(changeName);
   if (root)
     return dirname11(projectLayout(root).stateFile(changeName));
   if (!deps.useWorktree)
     return dirname11(projectLayout(deps.projectRoot).stateFile(changeName));
-  const wtPath = join27(worktreesDir2(deps.projectRoot), changeName);
+  const wtPath = join28(worktreesDir2(deps.projectRoot), changeName);
   const statePath = projectLayout(wtPath).stateFile(changeName);
   if (await Bun.file(statePath).exists())
     return dirname11(statePath);
@@ -107520,7 +107972,7 @@ async function readReviewWatermark(stateDir) {
   const sidecar = await readSlotSidecar(stateDir, "review");
   if (sidecar)
     return sidecar.lastConsumedCommentAt ?? null;
-  const file2 = Bun.file(join27(stateDir, ".ralph-state.json"));
+  const file2 = Bun.file(join28(stateDir, ".ralph-state.json"));
   if (!await file2.exists())
     return null;
   try {
@@ -107732,7 +108184,7 @@ var init_github = __esm(() => {
 
 // apps/agent/src/agent/wire/mention-scan.ts
 import { readdir as readdir2 } from "fs/promises";
-import { join as join28 } from "path";
+import { join as join29 } from "path";
 function createMentionScanner(input) {
   const {
     apiKey,
@@ -107898,7 +108350,7 @@ function createMentionScanner(input) {
 async function isChangeArchivedForIssue(issue2, cwdByChange, projectRoot) {
   const changeName = changeNameForIssue(issue2);
   const root = cwdByChange.get(changeName) ?? projectRoot;
-  const archiveDir = join28(projectLayout(root).tasksDir, "archive");
+  const archiveDir = join29(projectLayout(root).tasksDir, "archive");
   let entries;
   try {
     entries = await readdir2(archiveDir);
@@ -107922,9 +108374,9 @@ var init_mention_scan = __esm(() => {
 });
 
 // apps/agent/src/agent/wire/spawn/default.ts
-import { join as join29 } from "path";
+import { join as join30 } from "path";
 function defaultSpawn(changeName, cmd, cwd2, logsDir, onWorkerOutput, note) {
-  const logFilePath = join29(logsDir, `${changeName}.log`);
+  const logFilePath = join30(logsDir, `${changeName}.log`);
   const ANSI_RE2 = /\x1b(?:\[[0-9;]*[A-Za-z]|\][^\x07\x1b]*(?:\x07|\x1b\\)|.)/g;
   const BOX_ONLY_RE = /^[\s\u2500\u2502\u256D\u256E\u2570\u256F\u254C\u2504\u2501\u2503]+$/;
   const STATUS_BAR_LINE_RE = /^[\u280B\u2819\u2839\u2838\u283C\u2834\u2826\u2827\u2807\u280F\u2713\u2717]\s+iter\s+\d+/;
@@ -107985,16 +108437,16 @@ var init_default2 = __esm(() => {
 });
 
 // apps/agent/src/agent/state/agent-run-state.ts
-import { basename as basename3, join as join30 } from "path";
+import { basename as basename3, join as join31 } from "path";
 import { homedir as homedir6 } from "os";
 import { mkdir as mkdir9, writeFile } from "fs/promises";
 function agentRunStatePath(projectRoot) {
-  return join30(homedir6(), ".ralph", basename3(projectRoot), "agent-state.json");
+  return join31(homedir6(), ".ralph", basename3(projectRoot), "agent-state.json");
 }
 async function writeAgentRunState(state) {
   const path = agentRunStatePath(state.projectRoot);
   try {
-    await mkdir9(join30(homedir6(), ".ralph", basename3(state.projectRoot)), { recursive: true });
+    await mkdir9(join31(homedir6(), ".ralph", basename3(state.projectRoot)), { recursive: true });
     await writeFile(path, JSON.stringify(state, null, 2) + `
 `, "utf-8");
   } catch {}
@@ -108021,17 +108473,17 @@ var CI_FAILED_EXIT2 = 70, PR_FAILED_EXIT2 = 71, NO_CHANGES_EXIT2 = 72;
 // packages/retro/src/paths.ts
 import { homedir as homedir7 } from "os";
 import { mkdir as mkdir10 } from "fs/promises";
-import { join as join31 } from "path";
+import { join as join32 } from "path";
 function retroDir() {
-  return join31(homedir7(), ".ralph", "retro");
+  return join32(homedir7(), ".ralph", "retro");
 }
 async function resolveRetroOutputPath(identifier, date5, dir = retroDir()) {
   await mkdir10(dir, { recursive: true });
-  const base2 = join31(dir, `${identifier}-${date5}.md`);
+  const base2 = join32(dir, `${identifier}-${date5}.md`);
   if (!await Bun.file(base2).exists())
     return base2;
   for (let n = 2;; n++) {
-    const candidate = join31(dir, `${identifier}-${date5}-${n}.md`);
+    const candidate = join32(dir, `${identifier}-${date5}-${n}.md`);
     if (!await Bun.file(candidate).exists())
       return candidate;
   }
@@ -108145,7 +108597,7 @@ var init_retro = __esm(() => {
 });
 
 // apps/agent/src/agent/wire/spawn/worker.ts
-import { join as join32 } from "path";
+import { join as join33 } from "path";
 function localDateStamp(d) {
   const y = d.getFullYear();
   const m = String(d.getMonth() + 1).padStart(2, "0");
@@ -108276,7 +108728,7 @@ function createSpawnWorker(input) {
         paths: {
           changeDir: info.changeDir,
           stateFilePath: info.stateFilePath,
-          logFile: join32(logsDir, `${info.changeName}.log`),
+          logFile: join33(logsDir, `${info.changeName}.log`),
           jsonLogFile: args.jsonLogFile ?? null,
           agentStateFile: agentRunStatePath(projectRoot)
         }
@@ -108293,7 +108745,7 @@ function createSpawnWorker(input) {
   return function spawnWorker(changeName, _issue, trigger) {
     const cwd2 = cwdByChange.get(changeName) ?? projectRoot;
     const injected = runners?.spawnWorker;
-    const missionTasksPath = join32(projectLayout(cwd2).changeDir(changeName), MISSION_TASKS_FILENAME);
+    const missionTasksPath = join33(projectLayout(cwd2).changeDir(changeName), MISSION_TASKS_FILENAME);
     const prevTasksPromise = (async () => {
       const f2 = Bun.file(missionTasksPath);
       return await f2.exists() ? await f2.text() : "";
@@ -108301,7 +108753,7 @@ function createSpawnWorker(input) {
     let logFilePath;
     let handle;
     if (injected) {
-      logFilePath = join32(logsDir, `${changeName}.log`);
+      logFilePath = join33(logsDir, `${changeName}.log`);
       handle = injected(buildTaskCmdFor(changeName), cwd2);
     } else {
       const r = defaultSpawn(changeName, buildTaskCmdFor(changeName), cwd2, logsDir, onWorkerOutput, `spawn at ${new Date().toISOString()}`);
@@ -108323,7 +108775,7 @@ function createSpawnWorker(input) {
     const wantAutoMerge = issueForChange ? issueMatchesGetIndicator(issueForChange, indicators.getAutoMerge) : false;
     const wrapped = handle.exited.then(async (code) => {
       const workerLayout = projectLayout(cwd2);
-      const validateSpecPath = join32(workerLayout.changeDir(changeName), "specs", "validate.md");
+      const validateSpecPath = join33(workerLayout.changeDir(changeName), "specs", "validate.md");
       const hasValidateSpec = await Bun.file(validateSpecPath).exists();
       const wantValidateOnly = hasValidateSpec && !wantPrBase;
       if (hasValidateSpec) {
@@ -108807,7 +109259,7 @@ var init_linear_sync = __esm(() => {
 });
 
 // apps/agent/src/agent/linear-sync/comment-sync.ts
-import { dirname as dirname12, join as join33 } from "path";
+import { dirname as dirname12, join as join34 } from "path";
 async function readInlineLinearComments(statePath) {
   const file2 = Bun.file(statePath);
   if (!await file2.exists())
@@ -108848,7 +109300,7 @@ function isCommentNotFoundError(err) {
   return text.includes("not found") || text.includes("could not find") || text.includes("entity not found");
 }
 async function readTasksMd(changeDir, log3) {
-  const file2 = Bun.file(join33(changeDir, "tasks.md"));
+  const file2 = Bun.file(join34(changeDir, "tasks.md"));
   if (!await file2.exists()) {
     log3(`  comment-sync: tasks.md missing in ${changeDir}, skipping`, "gray");
     return null;
@@ -108954,14 +109406,14 @@ async function postPlanCommentOnce(deps) {
   const check2 = parsePlanningSection(tasksMd);
   if (!check2.allChecked)
     return null;
-  const proposalPath = join33(deps.changeDir, "proposal.md");
+  const proposalPath = join34(deps.changeDir, "proposal.md");
   const why = await readSection(proposalPath, "Why");
   const whatChanges = await readSection(proposalPath, "What Changes");
   if (!why && !whatChanges) {
     deps.log(`  comment-sync: proposal.md has no Why/What Changes, skipping plan comment`, "gray");
     return null;
   }
-  const designSummary = await readFirstParagraph(join33(deps.changeDir, "design.md"));
+  const designSummary = await readFirstParagraph(join34(deps.changeDir, "design.md"));
   const parts = [`### ${PLAN_COMMENT_TITLE} \u2014 \`${deps.changeName}\``];
   if (why) {
     parts.push("", "**Why**", "", why);
@@ -111615,11 +112067,11 @@ var require_tslib = __commonJS((exports, module) => {
     };
     __awaiter = function(thisArg, _arguments, P, generator) {
       function adopt(value) {
-        return value instanceof P ? value : new P(function(resolve3) {
-          resolve3(value);
+        return value instanceof P ? value : new P(function(resolve4) {
+          resolve4(value);
         });
       }
-      return new (P || (P = Promise))(function(resolve3, reject2) {
+      return new (P || (P = Promise))(function(resolve4, reject2) {
         function fulfilled(value) {
           try {
             step(generator.next(value));
@@ -111635,7 +112087,7 @@ var require_tslib = __commonJS((exports, module) => {
           }
         }
         function step(result2) {
-          result2.done ? resolve3(result2.value) : adopt(result2.value).then(fulfilled, rejected);
+          result2.done ? resolve4(result2.value) : adopt(result2.value).then(fulfilled, rejected);
         }
         step((generator = generator.apply(thisArg, _arguments || [])).next());
       });
@@ -111864,14 +112316,14 @@ var require_tslib = __commonJS((exports, module) => {
       }, i);
       function verb(n) {
         i[n] = o[n] && function(v) {
-          return new Promise(function(resolve3, reject2) {
-            v = o[n](v), settle(resolve3, reject2, v.done, v.value);
+          return new Promise(function(resolve4, reject2) {
+            v = o[n](v), settle(resolve4, reject2, v.done, v.value);
           });
         };
       }
-      function settle(resolve3, reject2, d, v) {
+      function settle(resolve4, reject2, d, v) {
         Promise.resolve(v).then(function(v2) {
-          resolve3({ value: v2, done: d });
+          resolve4({ value: v2, done: d });
         }, reject2);
       }
     };
@@ -112734,9 +113186,9 @@ var require_clone = __commonJS((exports, module) => {
         } else if (_instanceof2(parent2, nativeSet)) {
           child = new nativeSet;
         } else if (_instanceof2(parent2, nativePromise)) {
-          child = new nativePromise(function(resolve3, reject2) {
+          child = new nativePromise(function(resolve4, reject2) {
             parent2.then(function(value) {
-              resolve3(_clone(value, depth2 - 1));
+              resolve4(_clone(value, depth2 - 1));
             }, function(err) {
               reject2(_clone(err, depth2 - 1));
             });
@@ -260785,7 +261237,7 @@ function toPdfSafe(text) {
   return out;
 }
 function renderMarkdownToPdf(md, title) {
-  return new Promise((resolve3, reject2) => {
+  return new Promise((resolve4, reject2) => {
     try {
       const doc2 = new PDFDocument({
         size: PAGE_SIZE,
@@ -260794,7 +261246,7 @@ function renderMarkdownToPdf(md, title) {
       });
       const chunks = [];
       doc2.on("data", (chunk2) => chunks.push(chunk2));
-      doc2.on("end", () => resolve3(new Uint8Array(Buffer.concat(chunks))));
+      doc2.on("end", () => resolve4(new Uint8Array(Buffer.concat(chunks))));
       doc2.on("error", reject2);
       doc2.fillColor(COLOR_TEXT).font(FONT_BODY).fontSize(BODY_SIZE);
       const tokens = g.lexer(md);
@@ -261237,7 +261689,7 @@ var init_render_pdf = __esm(() => {
 });
 
 // apps/agent/src/agent/linear-sync/spec-attachments.ts
-import { dirname as dirname13, join as join34 } from "path";
+import { dirname as dirname13, join as join35 } from "path";
 function describeLinearError(err) {
   const e = err;
   const parts = [e.message ?? String(err)];
@@ -261346,7 +261798,7 @@ async function syncSlot(deps, slot) {
   const [primaryName, ...trailingNames] = spec.sourceFiles;
   if (!primaryName)
     return;
-  const primary = Bun.file(join34(deps.changeDir, primaryName));
+  const primary = Bun.file(join35(deps.changeDir, primaryName));
   if (!await primary.exists()) {
     deps.log(`  spec-attachments: ${primaryName} missing, skipping`, "gray");
     return;
@@ -261365,7 +261817,7 @@ async function syncSlot(deps, slot) {
   const parts = [primaryBytes];
   const enc = new TextEncoder;
   for (const name of trailingNames) {
-    const f2 = Bun.file(join34(deps.changeDir, name));
+    const f2 = Bun.file(join35(deps.changeDir, name));
     if (!await f2.exists())
       continue;
     let raw;
@@ -261633,9 +262085,9 @@ var init_comment_sync2 = __esm(() => {
 });
 
 // apps/agent/src/features/pr-tracker/state.ts
-import { join as join35 } from "path";
+import { join as join36 } from "path";
 async function readState2(projectRoot) {
-  const path = join35(projectRoot, PR_TRACKER_STATE_RELPATH);
+  const path = join36(projectRoot, PR_TRACKER_STATE_RELPATH);
   const file2 = Bun.file(path);
   if (!await file2.exists())
     return {};
@@ -261651,7 +262103,7 @@ async function readState2(projectRoot) {
   }
 }
 async function writeState2(projectRoot, state) {
-  const path = join35(projectRoot, PR_TRACKER_STATE_RELPATH);
+  const path = join36(projectRoot, PR_TRACKER_STATE_RELPATH);
   await Bun.write(path, JSON.stringify(state, null, 2));
 }
 var PR_TRACKER_STATE_RELPATH = ".ralph/pr-tracker-state.json";
@@ -261730,7 +262182,7 @@ var init_pr_tracker = __esm(() => {
 });
 
 // apps/agent/src/agent/wire.ts
-import { join as join36 } from "path";
+import { join as join37 } from "path";
 function buildAgentCoordinator(input) {
   const {
     args,
@@ -261749,7 +262201,7 @@ function buildAgentCoordinator(input) {
     onWorkerCmd,
     onAwaitingTicket
   } = input;
-  const logsDir = join36(projectRoot, ".ralph", "logs");
+  const logsDir = join37(projectRoot, ".ralph", "logs");
   const bus = createBus();
   subscribeAgentDiag(bus, onLog);
   const diag = (area, message, color) => {
@@ -261775,7 +262227,11 @@ function buildAgentCoordinator(input) {
   const awaitingChangeSet = new Set;
   const coordRef = { current: null };
   let pollContext = new PollContext;
-  const useWorktree = args.worktree || cfg.useWorktree;
+  let useWorktree = args.worktree || cfg.useWorktree;
+  if (concurrency > 1 && !useWorktree) {
+    diag("config", `! concurrency is ${concurrency} but useWorktree is off \u2014 forcing worktrees on so parallel tasks get isolated working copies`, "yellow");
+    useWorktree = true;
+  }
   const scriptRunner = input.runners?.runScript ?? (async (cmd, cwd2) => {
     const proc = Bun.spawn({
       cmd: ["sh", "-c", cmd],
@@ -261980,7 +262436,7 @@ function buildAgentCoordinator(input) {
       const changeDir = projectLayout(root).changeDir(changeName);
       const parts = [];
       for (const name of ["tasks.md", "proposal.md", "design.md"]) {
-        const file2 = Bun.file(join36(changeDir, name));
+        const file2 = Bun.file(join37(changeDir, name));
         if (!await file2.exists())
           continue;
         parts.push(`${name}:${file2.lastModified}:${file2.size}`);
@@ -262025,7 +262481,7 @@ function buildAgentCoordinator(input) {
     getGaveUpTotal: async () => {
       let total = 0;
       for (const [changeName, root] of cwdByChange) {
-        const file2 = Bun.file(join36(projectLayout(root).taskStateDir(changeName), GAVEUP_COUNT_FILE));
+        const file2 = Bun.file(join37(projectLayout(root).taskStateDir(changeName), GAVEUP_COUNT_FILE));
         if (!await file2.exists())
           continue;
         try {
@@ -262092,7 +262548,7 @@ async function waitForActiveWorkers(deps) {
   const budgetMs = deps.budgetMs ?? 1e4;
   const warnAtMs = deps.warnAtMs ?? 5000;
   deps.stop();
-  await new Promise((resolve3) => {
+  await new Promise((resolve4) => {
     const start = Date.now();
     let warned = false;
     const wait = setInterval(() => {
@@ -262100,7 +262556,7 @@ async function waitForActiveWorkers(deps) {
       const elapsed = Date.now() - start;
       if (active === 0) {
         clearInterval(wait);
-        resolve3();
+        resolve4();
         return;
       }
       if (!warned && elapsed >= warnAtMs) {
@@ -262110,7 +262566,7 @@ async function waitForActiveWorkers(deps) {
       if (elapsed >= budgetMs) {
         clearInterval(wait);
         deps.onTimeout?.(active);
-        resolve3();
+        resolve4();
       }
     }, 100);
   });
@@ -262313,7 +262769,7 @@ var init_output_utils = __esm(() => {
 });
 
 // apps/agent/src/agent/state/worker-state-poll.ts
-import { join as join37 } from "path";
+import { join as join38 } from "path";
 function parseSubtasks(tasksMd) {
   const out = [];
   let skipSection = false;
@@ -262346,7 +262802,7 @@ function initialWorkerSnapshot() {
 async function readWorkerSnapshot(input) {
   const next = { ...input.prev };
   try {
-    const file2 = Bun.file(join37(input.statesDir, input.changeName, ".ralph-state.json"));
+    const file2 = Bun.file(join38(input.statesDir, input.changeName, ".ralph-state.json"));
     if (await file2.exists()) {
       const json2 = await file2.json();
       next.iter = json2.iteration ?? next.iter;
@@ -262355,10 +262811,10 @@ async function readWorkerSnapshot(input) {
   } catch {}
   if (input.changeDir) {
     try {
-      const tasksFile = Bun.file(join37(input.changeDir, "tasks.md"));
-      const proposalFile = Bun.file(join37(input.changeDir, "proposal.md"));
-      const designFile = Bun.file(join37(input.changeDir, "design.md"));
-      const reviewFindingsFile = Bun.file(join37(input.changeDir, "review-findings.md"));
+      const tasksFile = Bun.file(join38(input.changeDir, "tasks.md"));
+      const proposalFile = Bun.file(join38(input.changeDir, "proposal.md"));
+      const designFile = Bun.file(join38(input.changeDir, "design.md"));
+      const reviewFindingsFile = Bun.file(join38(input.changeDir, "review-findings.md"));
       const [tasksText, proposalText, designText, reviewFindingsText] = await Promise.all([
         tasksFile.exists().then((ok) => ok ? tasksFile.text() : null),
         proposalFile.exists().then((ok) => ok ? proposalFile.text() : null),
@@ -262421,7 +262877,7 @@ var init_worker_state_poll = __esm(() => {
 });
 
 // apps/agent/src/components/AgentMode.tsx
-import { join as join38 } from "path";
+import { join as join39 } from "path";
 async function appendSteeringImpl(changeDir, message) {
   await runWithContext(createDefaultContext(), async () => {
     appendSteeringMessage(changeDir, message);
@@ -262695,8 +263151,8 @@ function AgentMode({
     let cancelled = false;
     async function init2() {
       logSession(`=== session start ${SESSION_START} ===`);
-      const cfgPath = await ensureConfig(projectRoot);
-      const cfg2 = await loadConfig(projectRoot);
+      const cfgPath = await ensureConfig(projectRoot, args.workflowFile);
+      const cfg2 = await loadConfig(projectRoot, args.workflowFile);
       cfgRef.current = cfg2;
       appendLog(`agent mode v${VERSION} \u2014 config: ${cfgPath}`, "gray");
       const apiKey = process.env["LINEAR_API_KEY"];
@@ -263994,7 +264450,7 @@ function AgentMode({
                     },
                     onSubmit: async (message) => {
                       try {
-                        await appendSteering2(join38(tasksDir, w2.changeName), message);
+                        await appendSteering2(join39(tasksDir, w2.changeName), message);
                         fileEmit({ type: "steering_submitted", changeName: w2.changeName, message });
                       } catch (err) {
                         const text = err.message;
@@ -264298,7 +264754,7 @@ __export(exports_list, {
   buildBuckets: () => buildBuckets,
   backlogRankByIssueId: () => backlogRankByIssueId
 });
-import { join as join39 } from "path";
+import { join as join40 } from "path";
 function countTaskItems(content) {
   const checked = (content.match(/^- \[x\]/gm) ?? []).length;
   const unchecked = (content.match(/^- \[ \]/gm) ?? []).length;
@@ -264314,13 +264770,13 @@ function buildLocalRows() {
   const sources = [{ dir: statesDir, label: "main" }];
   const worktreesRoot = worktreesDir2(projectRoot);
   for (const wt of storage.list(worktreesRoot)) {
-    sources.push({ dir: join39(worktreesRoot, wt, ".ralph", "tasks"), label: `wt:${wt}` });
+    sources.push({ dir: join40(worktreesRoot, wt, ".ralph", "tasks"), label: `wt:${wt}` });
   }
   for (const { dir, label } of sources) {
     for (const entry of storage.list(dir)) {
       if (seen.has(entry))
         continue;
-      const raw = storage.read(join39(dir, entry, ".ralph-state.json"));
+      const raw = storage.read(join40(dir, entry, ".ralph-state.json"));
       if (raw === null)
         continue;
       let state;
@@ -264335,7 +264791,7 @@ function buildLocalRows() {
       const firstLine = promptRaw.split(`
 `).find((l3) => l3.trim() !== "") ?? "";
       let progress = "\u2014";
-      const tasksContent = storage.read(join39(dir, entry, "tasks.md"));
+      const tasksContent = storage.read(join40(dir, entry, "tasks.md"));
       if (tasksContent !== null) {
         const { checked, unchecked } = countTaskItems(tasksContent);
         const total = checked + unchecked;
@@ -264600,7 +265056,7 @@ async function runList(input) {
   }
   const rows = buildLocalRows();
   printLocalRows(rows);
-  const cfg = await loadRalphyConfig(projectRoot);
+  const cfg = await loadRalphyConfig(projectRoot, getArgs().workflowFile);
   const apiKey = process.env["LINEAR_API_KEY"];
   const indicators = cfg.linear.indicators;
   const team = input.linearTeamOverride || cfg.linear.team;
@@ -264724,7 +265180,7 @@ async function runListDebug(input) {
     process.exitCode = 1;
     return;
   }
-  const cfg = await loadRalphyConfig(projectRoot);
+  const cfg = await loadRalphyConfig(projectRoot, getArgs().workflowFile);
   const indicators = cfg.linear.indicators;
   const team = input.linearTeamOverride || cfg.linear.team;
   const { assignee, anyAssignee } = resolveLinearFilter(input.linearFilterOverride, input.linearAssigneeOverride, cfg.linear.filter);
@@ -264835,7 +265291,7 @@ var exports_json_runner = {};
 __export(exports_json_runner, {
   runAgentJson: () => runAgentJson
 });
-import { join as join40 } from "path";
+import { join as join41 } from "path";
 import { mkdir as mkdir12 } from "fs/promises";
 import { homedir as homedir8 } from "os";
 function makeEmit(fileSink) {
@@ -264857,13 +265313,13 @@ async function runAgentJson({
   tasksDir,
   runPreflight: runPreflight2 = runPreflight
 }) {
-  await mkdir12(join40(homedir8(), ".ralph"), { recursive: true }).catch(() => {
+  await mkdir12(join41(homedir8(), ".ralph"), { recursive: true }).catch(() => {
     return;
   });
   const fileSink = createJsonLogFileSink(args.jsonLogFile);
   const emit3 = makeEmit(fileSink);
-  const cfgPath = await ensureRalphyConfig(projectRoot);
-  const cfg = await loadRalphyConfig(projectRoot);
+  const cfgPath = await ensureRalphyConfig(projectRoot, args.workflowFile);
+  const cfg = await loadRalphyConfig(projectRoot, args.workflowFile);
   await writeAgentRunState({
     projectRoot,
     configPath: cfgPath,
@@ -265020,7 +265476,7 @@ async function runAgentJson({
       }
     })();
   }, 1000);
-  await new Promise((resolve3) => {
+  await new Promise((resolve4) => {
     let shuttingDown = false;
     const onSig = () => {
       if (shuttingDown) {
@@ -265050,7 +265506,7 @@ async function runAgentJson({
           });
           setTimeout(() => process.exit(1), 50);
         }
-      }).then(() => resolve3());
+      }).then(() => resolve4());
     };
     process.once("SIGINT", onSig);
     process.once("SIGTERM", onSig);
@@ -265074,7 +265530,7 @@ __export(exports_src3, {
   main: () => main3
 });
 import { mkdir as mkdir13 } from "fs/promises";
-import { join as join41 } from "path";
+import { join as join42 } from "path";
 async function main3(argv) {
   if (argv.includes("--help") || argv.includes("-h")) {
     printAgentHelp();
@@ -265128,7 +265584,7 @@ async function main3(argv) {
   if (args.ticketTokens.length > 0) {
     const { loadRalphyConfig: loadRalphyConfig2 } = await Promise.resolve().then(() => (init_config(), exports_config));
     const { resolveTicketNumbers: resolveTicketNumbers2, formatTicketError: formatTicketError2 } = await Promise.resolve().then(() => (init_linear_client(), exports_linear_client));
-    const cfg = await loadRalphyConfig2(projectRoot);
+    const cfg = await loadRalphyConfig2(projectRoot, args.workflowFile);
     const team = args.linearTeam || cfg.linear.team;
     try {
       resolveTicketNumbers2(args.ticketTokens, team);
@@ -265140,7 +265596,7 @@ async function main3(argv) {
   }
   await mkdir13(statesDir, { recursive: true });
   await mkdir13(tasksDir, { recursive: true });
-  await mkdir13(join41(projectRoot, ".ralph"), { recursive: true });
+  await mkdir13(join42(projectRoot, ".ralph"), { recursive: true });
   if (shouldFallbackToJsonOutput(args, process.stdin.isTTY)) {
     process.stderr.write(`agent: stdin is not a TTY \u2014 falling back to --json-output mode.
 `);
@@ -265198,6 +265654,7 @@ var init_src8 = __esm(async () => {
 init_src();
 init_src2();
 init_version();
+init_common_args();
 if (typeof globalThis.Bun === "undefined") {
   process.stderr.write(`ralphy requires the Bun runtime (https://bun.sh/). It is not compatible with plain Node.js.
 ` + "Install Bun and re-run with `bun` or `bunx ralphy`.\n");
@@ -265282,7 +265739,8 @@ ${HELP}
     if (shouldOfferSetup(subcommand, argv.slice(1))) {
       try {
         const { maybeRunSetupWizard: maybeRunSetupWizard2 } = await init_src4().then(() => exports_src);
-        await maybeRunSetupWizard2();
+        const { projectRoot, workflowFile } = parseWorkflowPathArgs(argv.slice(1));
+        await maybeRunSetupWizard2(projectRoot, workflowFile);
       } catch (setupErr) {
         captureError("setup_wizard_error", setupErr, { subcommand });
       }