docks-kit 0.5.0 → 0.7.0

package/AGENTS.md

@@ -15,9 +15,9 @@ Tool-specific instructions live alongside this file:
 | Path | Purpose |
 |------|---------|
 | `docks-kit` | CLI launcher: runs the compiled binary in `cli/dist/` when present, otherwise Bun-from-source (auto-installs Bun + `node_modules`). No-Bun recovery is the platform release binary |
-| `cli/src/engine-native/` | EngineNative implementation for `sync`, `model`, and `toolchain`; idempotent, flag-gated for destructive reconciliation |
+| `cli/src/engine-native/` | EngineNative implementation for `sync`, `model`, `workflow`, and `toolchain`; idempotent, flag-gated for destructive reconciliation |
 | `cli/` | Effect-TS CLI + bundled docs topics |
-| `SoT/models.json` | Kit-verified model catalog |
+| `SoT/models.json` | Kit-verified model catalog plus the strict Docks workflow-role registry |
 | `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative) |
 | `SoT/.claude/bin/` | Dependency-free Bun runtime programs for Claude's statusline, SessionStart, and Notification |
 | `install.sh` | Global installer |
@@ -32,9 +32,11 @@ Tool-specific instructions live alongside this file:
 
 Codex SoT notes:
 - `SoT/.codex/AGENTS.md` deploys to `~/.codex/AGENTS.md` as global Codex instructions.
-- `SoT/.codex/config.toml` pins Codex to `model = "gpt-5.6-sol"`, sets reasoning effort/summaries (`xhigh` + `detailed`), `model_verbosity = "medium"`, `personality`, live top-level `web_search`, workspace-write sandboxing with sandboxed command network access, cross-session `memories` (+ dedicated note tools), `[agents]` subagent limits (`max_threads = 12`, `max_depth = 2` — intentionally above Codex defaults for broad parallel kit work; deeper recursion increases cost and predictability risk), a 128 KiB `project_doc_max_bytes` budget for the repo-side AGENTS.md chain (the global `~/.codex/AGENTS.md` is uncapped and not counted), and enables the Docks plugins as `docks@docks` + `session-relay@docks`.
+- `SoT/.codex/config.toml` pins Codex to `model = "gpt-5.6-sol"`, sets reasoning effort/summaries (`xhigh` + `concise`), `model_verbosity = "low"`, `personality`, live top-level `web_search`, workspace-write sandboxing with sandboxed command network access, cross-session `memories` (+ dedicated note tools), `[agents]` subagent limits (`max_threads = 12`, `max_depth = 2` — intentionally above Codex defaults for broad parallel kit work; deeper recursion increases cost and predictability risk), a 128 KiB `project_doc_max_bytes` budget for the repo-side AGENTS.md chain (the global `~/.codex/AGENTS.md` is uncapped and not counted), and enables the Docks plugins as `docks@docks`, `session-relay@docks`, and `effect-kit@docks`.
 - `SoT/.codex/rules/*.rules` deploys to `~/.codex/rules/` as kit-managed Codex command policy. This is Codex's equivalent of permission allow/prompt/block rules; user-learned approvals in `~/.codex/rules/default.rules` are preserved.
 - `SoT/.codex/plugins/marketplace.json` deploys to Codex's personal marketplace path at `~/.agents/plugins/marketplace.json`; when the `codex` CLI is available, sync reruns `codex plugin add <plugin@marketplace>` for enabled SoT plugins so stale cached installs are refreshed.
+- `docks-kit status` verifies Session Relay only through the supported `codex plugin list --json` inventory. `ready` means installed and enabled for a newly started Codex session; it is not evidence about an old process, lifecycle state, receive-path health, or worker quiescence. The global prompt SoTs carry the owner's standing authorization for Docks cross-company plan review, which never overrides host or platform denial.
+- Both global prompt SoTs carry one byte-identical compact `Docks-workflow-models:` record. Root `--model-orchestrator` / `--model-reviewer` / `--model-implementer` / review-bound flags update only that deployed record; `docks-kit models workflow` lists the closed selectors, and a flag-less sync restores defaults.
 - The `codex` CLI binary is upstream-owned, not kit-owned. The official standalone installer keeps package metadata under `$CODEX_HOME/packages/standalone` and places the `codex` symlink in `~/.local/bin` by default; sync only warns with a download-then-run installer command when the CLI is missing. Existing installs can self-update with `codex update`; npm and Homebrew remain upstream alternatives.
 - `SoT/.codex/AGENTS.md` deliberately does not import `@RTK.md`: RTK's published Codex integration is prompt-file based rather than hook based, so importing it leaks implementation detail into agent-visible context. Use Codex hooks for RTK only after the kit installs a hook-backed Codex integration.
 - Claude runtime settings are an authoring template with sentinels. `claudeRuntime.ts` materializes absolute Bun/script paths only after the shared `bun.ts` bootstrap is ready; `claudeSync.ts` writes all runtime assets before atomically committing settings, then prunes the legacy shell scripts and Stop hook. Native `rate_limits` is the sole quota source, so jq/curl/OAuth caches are not runtime dependencies. A missing Bun defers only this cutover and preserves legacy pointers/files.
@@ -70,6 +72,8 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT d
 
 Automated coverage includes `bun run test:unit`, `bun run golden:dryrun`, and `bun run golden:mutation`; prove-red modes must exit non-zero after detecting planted mismatches. Also verify user-facing changes via `./docks-kit sync --dry-run`, per-tool sanity (`/doctor`, `/plugin`, etc.), and `diff <(jq -S . <SoT>) <(jq -S . <deployed>)` recipes from the per-tool file.
 
+Use direct acceptance and focused regressions while iterating, then run the full unit/golden gate once at the pre-commit or release boundary. Reuse still-matching evidence; a later relevant edit invalidates only the affected rung and final gate, not every prior check.
+
 ## Skills
 
 This project ships **kit-mechanic skills** under `.claude/skills/` — narrowly-scoped references for how EngineNative works (settings merge, plugin bootstrap, universal-skill install, Codex TOML merge, sync orchestration). They cost prompt tokens only inside this repo's sessions and document regression-prone TypeScript sync logic in `cli/src/engine-native/`. **Pipeline content** (multi-agent slash commands, refactor/security/docs workflows, parallel-scanner agents) belongs in the separate [DocksDocks/docks](https://github.com/DocksDocks/docks) plugin — not here. Project-level agents under `.claude/agents/` follow the same rule: kit-mechanic agents that wrap kit-mechanic skills are permitted; pipeline agents live in the docks plugin.
@@ -83,10 +87,10 @@ When a kit-mechanic skill, its `references/`, or a wrapper agent (`.claude/agent
 ## Plans
 
 <constraint>
-Multi-commit work plans live in `docs/plans/active/` (status is a frontmatter field) and `docs/plans/finished/` (archive). Every plan file is a complete handoff document — `goal`, `Steps`, `Acceptance criteria`, `Review` — so any agent can pick one up cold. Skills handle every operation: `plan-init` (bootstrap/migrate), `plan-manager` (list/show/start/block/ship/new, auto-commit on transition, self-review on draft), `plan-review` (verification). Trigger by natural language or the matching `plan-*` skill. `active/` is multi-occupancy.
+Multi-commit work plans live in `docs/plans/active/` (status is a frontmatter field) and `docs/plans/finished/` (archive). Every plan file is a complete cold-handoff document — goal, context & rationale, environment & how-to-run, steps with exact paths, executable acceptance criteria, and a binary cold-handoff checklist — so any agent (or a weaker model) can pick one up cold without guessing. Skills handle every operation: `plan-init` (bootstrap/migrate), `plan-manager` (list/show/start/block/ship/new, auto-commit on transition, self-review on draft), `plan-review` (verification). Trigger by natural language or the matching `plan-*` skill. `active/` is multi-occupancy.
 </constraint>
 
-The full convention (frontmatter schema, body sections, self-review loop, open-questions, age tokens) lives in `docs/plans/AGENTS.md`. `docs/plans/CLAUDE.md` is a one-line `@AGENTS.md` import for Claude Code's nested discovery.
+The full convention (frontmatter schema, body sections, one-pass local self-review, bounded strong-default X/S review receipts, workflow roles, open-questions, age tokens) lives in `docs/plans/AGENTS.md`. `docs/plans/CLAUDE.md` is a one-line `@AGENTS.md` import for Claude Code's nested discovery. If `.codex/agents/plan-manager.toml` and `.codex/agents/plan-review.toml` exist, Codex may use them for explicit subagent delegation; otherwise run the matching `plan-*` skill inline.
 
 Distinct from per-tool **Open Concerns** sections (wait-on-upstream
 blockers tied to a vendor shipping a fix — these live inside the per-tool

package/README.md

@@ -39,7 +39,7 @@ RTK/Bun download boundaries, not as a global sync prerequisite.
 docks-kit sync [claude] [codex] [agents]   deploy the SoT (default: all three)
 docks-kit update [--no-sync]               self-update the kit (autodetects checkout vs global install), then sync
 docks-kit model <claude|codex> [value]     get/set the DEPLOYED model (TTY picker)
-docks-kit models [tool] [--json]           kit-verified model catalog
+docks-kit models [claude|codex|workflow]   model and workflow-role catalogs (`--json`)
 docks-kit toolchain [check|ensure <tool>]  verified-version floors for external tools
 docks-kit status [--json]                  deployed-vs-SoT drift + toolchain + counts
 docks-kit plugins list [--json]            enabledPlugins tri-state vs installed
@@ -71,6 +71,21 @@ golden-regression coverage for dry-run output, mutation snapshots, and argv logs
 and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 (includes the old→new rename table for the pre-CLI `sync.sh` flags).
 
+### Docks workflow roles (root flags)
+
+| Flag | Effect |
+|------|--------|
+| `--model-orchestrator=<selector>` | Override the Docks orchestrator candidate/profile |
+| `--model-reviewer=<selector>` | Override the Docks reviewer candidate/profile |
+| `--model-implementer=<selector>` | Override the Docks implementer candidate/profile |
+| `--review-min-score=<0..100>` | Override the completion-review target |
+| `--review-max-rounds=<1..10>` | Bound completion-review batches |
+
+Selectors are strict `profile:<name>` or `<tool>:<model>@<effort>` values from
+`docks-kit models workflow`. These root flags update only the identical compact
+record in `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md`; omitted fields retain
+their current valid values, while a later flag-less sync restores all defaults.
+
 ## How syncing works
 
 - **Additive by default** — user-only settings keys, plugins, and skills
@@ -83,7 +98,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
   (`--yes` accepts; non-TTY falls back to the pinned verified version
   when possible). `docks-kit toolchain check` shows the full table.
 - **Model catalog** — `SoT/models.json` is the research-verified source for
-  model validation, listings, and pickers.
+  model validation, listings, pickers, and the Docks workflow-role registry.
 - **Claude runtime** — sync materializes three dependency-free Bun `.mjs`
   programs for statusline, SessionStart, and Notification. Quota display uses
   Claude's native `rate_limits`; there is no OAuth fetch, shared usage cache,
@@ -97,7 +112,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 | `SoT/.claude/` | Claude Code SoT (settings template, Bun runtime programs, CLAUDE.md) |
 | `SoT/.codex/` | Codex SoT (config.toml, rules, AGENTS.md, marketplace) |
 | `SoT/.agents/` | Universal-skill manifest |
-| `SoT/models.json` | Kit-verified model catalog |
+| `SoT/models.json` | Kit-verified model and Docks workflow-role catalog |
 | `SoT/toolchain.json` | Verified-version floors |
 | `cli/src/engine-native/` | EngineNative sync/model/toolchain implementation |
 | `cli/src/generated/sotPayload.ts` | Generated in-memory payload used by standalone and npm installs |

package/cli/docs/flags.md

@@ -39,6 +39,23 @@ Bare model, effort, or advisor modifiers print the relevant valid-value catalog
 and exit 2. A modifier for a target not selected by the positional arguments is
 ignored with a warning; Claude modifiers never touch Codex config and vice versa.
 
+## Docks workflow root flags
+
+These flags belong at the root (`docks-kit --model-reviewer=...`), not after
+`sync`. They update only the shared deployed workflow record.
+
+| Flag | Accepted value |
+|------|----------------|
+| `--model-orchestrator=<selector>` | `profile:<name>` or `<tool>:<model>@<effort>` |
+| `--model-reviewer=<selector>` | same strict selector grammar |
+| `--model-implementer=<selector>` | same strict selector grammar |
+| `--review-min-score=<n>` | base-10 integer `0..100` |
+| `--review-max-rounds=<n>` | base-10 integer `1..10` |
+
+Use `docks-kit models workflow [--json]` for the closed registry. Bare, empty,
+unknown, or malformed values print that helper and exit 2 before either prompt
+file changes.
+
 ## Renamed legacy flags (pre-CLI sync.sh)
 
 Old flags exit with a rename hint — there is no compat behavior.

package/cli/docs/models.md

@@ -31,8 +31,27 @@ docks-kit models claude --json    # machine-readable
 docks-kit model claude            # current deployed + SoT + picker (TTY)
 docks-kit model claude opus       # per-machine override from the Fable SoT
 docks-kit sync claude --claude-model=opus   # same, as part of a sync
+docks-kit models workflow             # Docks workflow profiles and defaults
+docks-kit models workflow --json      # closed machine-readable registry
 ```
 
+## Docks workflow-role registry
+
+The `workflow` section is strict even though ordinary tool-model modifiers are
+forward-compatible. It accepts only known `profile:<name>` values or exact
+`<tool>:<model>@<effort>` targets whose model and effort both appear in the
+catalog. The defaults are:
+
+- orchestrator: `profile:claude-best`, ordered as `claude:fable@high` then
+  `claude:opus@xhigh`;
+- reviewer and implementer: `codex:gpt-5.6-sol@xhigh`;
+- review minimum score 90 and maximum 3 rounds.
+
+`claude:best@high` is Claude's native one-model alias. It is deliberately not
+the same as the Docks-managed `profile:claude-best` candidate chain.
+Availability is `checked_when_used`: Docks classifies each launch attempt;
+docks-kit neither probes providers nor promises provider-wide fallback.
+
 ## Advisor pairing note (Claude)
 
 The SoT ships `model: fable` with advisor off (`advisorModel` unset).

package/cli/docs/modifiers.md

@@ -44,6 +44,29 @@ docks-kit model codex gpt-5.5     # codex flavor
 The set path calls the same engine functions as the sync flags —
 one implementation, two entry points.
 
+## Workflow-role overrides (root, no full sync)
+
+The root workflow flags are deployed modifiers for Docks rather than one tool:
+
+```text
+docks-kit --model-orchestrator=profile:claude-best \
+  --model-reviewer=codex:gpt-5.6-terra@high \
+  --review-min-score=80 --review-max-rounds=5
+```
+
+They atomically write one byte-identical complete record to
+`~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md`. Omitted fields retain the
+current valid record; a missing side is repaired. Invalid or conflicting state
+stops before mutation, a repeated request is a no-op, and failure on the second
+atomic write restores both snapshots. A later flag-less sync restores the
+embedded defaults. Start fresh sessions after changing the record.
+
+Selectors are strict `profile:<name>` or `<tool>:<model>@<effort>` entries from
+`docks-kit models workflow`. `profile:claude-best` is the ordered Docks
+Fable-high then Opus-xhigh chain; `claude:best@high` is instead Claude's native
+single-model alias. Docks checks each candidate when used—there is no docks-kit
+provider preflight.
+
 ## Sticky opt-ins are NOT modifiers
 
 `--claude-plugin=<name>` installs+enables an optional plugin and it STAYS

package/cli/src/commands/models.ts

@@ -2,9 +2,10 @@ import { Args, Command, Options } from "@effect/cli"
 import { Console, Effect, Option } from "effect"
 import { bail } from "../engine"
 import { modelCatalog, type Tool } from "../manifests"
+import { workflowCatalog, workflowRegistryJson } from "../workflowModels"
 
 const tool = Args.text({ name: "tool" }).pipe(
-  Args.withDescription("claude | codex (omit for both)"),
+  Args.withDescription("claude | codex | workflow (omit for both tool catalogs)"),
   Args.optional
 )
 const json = Options.boolean("json").pipe(
@@ -24,8 +25,11 @@ const renderTool = (t: Tool) =>
 export const modelsCommand = Command.make("models", { tool, json }, (config) =>
   Effect.gen(function* () {
     const requested = Option.getOrUndefined(config.tool)
+    if (requested === "workflow") {
+      return yield* Console.log(config.json ? workflowRegistryJson() : workflowCatalog())
+    }
     if (requested !== undefined && requested !== "claude" && requested !== "codex") {
-      return yield* bail(`Unknown tool '${requested}' (valid: claude, codex)`)
+      return yield* bail(`Unknown tool '${requested}' (valid: claude, codex, workflow)`)
     }
     const tools: Array<Tool> = requested !== undefined ? [requested as Tool] : ["claude", "codex"]
 
@@ -42,5 +46,5 @@ export const modelsCommand = Command.make("models", { tool, json }, (config) =>
     )
   })
 ).pipe(
-  Command.withDescription("List the kit-verified model catalog (SoT/models.json) for claude/codex.")
+  Command.withDescription("List kit-verified tool models or the Docks workflow role registry (SoT/models.json).")
 )

package/cli/src/commands/status.ts

@@ -10,6 +10,7 @@ import {
   sotCodexModel
 } from "../manifests"
 import { kitHome } from "../kitHome"
+import { sessionRelayReadiness } from "../engine-native/sessionRelayReadiness"
 
 const json = Options.boolean("json").pipe(
   Options.withDescription("Machine-readable output")
@@ -47,11 +48,12 @@ export const statusCommand = Command.make("status", { json }, (config) =>
     const drift = gatherDrift()
     const plugins = pluginsView()
     const skills = skillsView()
+    const sessionRelay = sessionRelayReadiness()
     const toolchainTable = yield* engineCapture(["toolchain", "check"])
 
     if (config.json) {
       return yield* Console.log(
-        JSON.stringify({ kitHome: kitHome(), drift, plugins, skills, toolchainTable }, null, 2)
+        JSON.stringify({ kitHome: kitHome(), drift, plugins, skills, sessionRelayReadiness: sessionRelay, toolchainTable }, null, 2)
       )
     }
 
@@ -67,6 +69,11 @@ export const statusCommand = Command.make("status", { json }, (config) =>
     yield* Console.log(
       `\nPlugins: ${plugins.length} known (${enabled} SoT-enabled) — details: docks-kit plugins list`
     )
+    yield* Console.log(
+      sessionRelay.state === "ready"
+        ? `Session Relay: ready for new Codex sessions (v${sessionRelay.version})`
+        : `Session Relay: unavailable for new Codex sessions (${sessionRelay.reason})`
+    )
     const installed = skills.filter((s) => s.installed).length
     yield* Console.log(
       `Skills:  ${skills.length} known (${installed} installed) — details: docks-kit skills list`
@@ -74,6 +81,6 @@ export const statusCommand = Command.make("status", { json }, (config) =>
   })
 ).pipe(
   Command.withDescription(
-    "Doctor view: deployed-vs-SoT drift (model, effort, compact window), toolchain table, plugin/skill counts."
+    "Doctor view: deployed-vs-SoT drift, toolchain, plugin/skill counts, and Session Relay readiness for new Codex sessions."
   )
 )

package/cli/src/engine-native/claudeSync.ts

@@ -31,6 +31,7 @@ import { ExitError } from "./parseArgs"
 import { mergeSettings, reconcileSettings } from "./settings"
 import { ensure, field } from "./toolchain"
 import { payloadBytes, payloadDisplayPath, payloadText } from "../payload"
+import { renderDefaultWorkflowInstructions } from "./workflowDeploy"
 
 export type ClaudeRuntimeState =
   | { readonly kind: "ready"; readonly paths: ClaudeRuntimePaths }
@@ -222,7 +223,7 @@ function syncClaudeMd(ctx: Ctx, claudeDir: string): void {
     return
   }
 
-  const source = payloadText("SoT/.claude/CLAUDE.md")
+  const source = renderDefaultWorkflowInstructions(payloadText("SoT/.claude/CLAUDE.md"))
   const stripReason = ctx.skipRtk ? "--skip-rtk" : rtkMdAbsent ? "~/.claude/RTK.md absent (rtk not initialized)" : ""
   if (stripReason !== "") {
     const stripped = source

package/cli/src/engine-native/codexSync.ts

@@ -10,7 +10,9 @@ import { syncCodexEffort, syncCodexModel, replaceTopLevelSettingInFile } from ".
 import { p } from "./exec"
 import type { Ctx } from "./index"
 import { compareCodepoints, isObject, jqStringify, parseJson, type Json } from "./jq"
+import { sessionRelayReadiness } from "./sessionRelayReadiness"
 import { payloadBytes, payloadDisplayPath, payloadPaths, payloadText, type PayloadPath } from "../payload"
+import { renderDefaultWorkflowInstructions } from "./workflowDeploy"
 
 export function codexSync(ctx: Ctx): void {
   const codexDir = p(ctx.home, ".codex")
@@ -23,7 +25,7 @@ export function codexSync(ctx: Ctx): void {
   syncCodexModel(ctx, ctx.codexModel)
   syncCodexEffort(ctx, ctx.codexEffort)
   syncRules(ctx, payloadPaths("SoT/.codex/rules/"), p(codexDir, "rules"))
-  syncAgentsMd(ctx, payloadText("SoT/.codex/AGENTS.md"), p(codexDir, "AGENTS.md"))
+  syncAgentsMd(ctx, renderDefaultWorkflowInstructions(payloadText("SoT/.codex/AGENTS.md")), p(codexDir, "AGENTS.md"))
   syncMarketplace(ctx, payloadText("SoT/.codex/plugins/marketplace.json"), p(ctx.agentsDir, "plugins", "marketplace.json"))
   removeLegacyDocksMarketplace(ctx, userConfig)
   syncPlugins(ctx, sotConfig)
@@ -476,6 +478,10 @@ function syncPlugins(ctx: Ctx, sotConfigText: string): void {
   if (refreshed > 0) {
     change(`Codex plugins synced (plugins: ~${refreshed})`)
     ctx.nextStepTriggers.codexRestart = true
+    const readiness = sessionRelayReadiness()
+    if (readiness.state !== "ready") {
+      warn(`Session Relay readiness unavailable after refresh: ${readiness.reason}`)
+    }
   }
   if (failed > 0) warn(`${failed} Codex plugin operation(s) failed — re-run sync or install manually`)
 }

package/cli/src/engine-native/index.ts

@@ -15,7 +15,8 @@ import { claudeNextSteps, claudeSummary, claudeSync } from "./claudeSync"
 import { codexNextSteps, codexSummary, codexSync } from "./codexSync"
 import { skillsNextSteps, skillsSummary, skillsSync } from "./skillsSync"
 import { modeModel, modeToolchain } from "./modes"
-import { ExitError, parseArgs, validateModifierFlags } from "./parseArgs"
+import { ExitError, parseArgs, parseWorkflowArgs, printWorkflowUsage, validateModifierFlags } from "./parseArgs"
+import { deployWorkflowOverrides } from "./workflowDeploy"
 
 export type ModifierFlag =
   | "--claude-model"
@@ -124,6 +125,19 @@ function engineSync(ctx: Ctx, args: ReadonlyArray<string>): number {
   return 0
 }
 
+function engineWorkflow(ctx: Ctx, args: ReadonlyArray<string>): number {
+  try {
+    const overrides = parseWorkflowArgs(ctx, args)
+    deployWorkflowOverrides(ctx, overrides)
+    return 0
+  } catch (error) {
+    if (error instanceof ExitError) throw error
+    printWorkflowUsage(ctx)
+    ctx.services.logger.err(error instanceof Error ? error.message : String(error))
+    throw new ExitError(2)
+  }
+}
+
 export function runEngineNative(argv: ReadonlyArray<string>, services?: EngineServices): number {
   let ctx!: Ctx
   const baseServices = services ?? makeEngineServices()
@@ -149,6 +163,8 @@ export function runEngineNative(argv: ReadonlyArray<string>, services?: EngineSe
         return modeModel(ctx, argv.slice(1))
       case "toolchain":
         return modeToolchain(ctx, argv.slice(1))
+      case "workflow":
+        return engineWorkflow(ctx, argv.slice(1))
       case "sync":
         return engineSync(ctx, argv.slice(1))
       default:

package/cli/src/engine-native/parseArgs.ts

@@ -16,6 +16,11 @@ import {
   isEffortModifierValue
 } from "../efforts"
 import { printModels, validateClaudeModel, validateCodexModel } from "./models"
+import {
+  buildWorkflowRecord,
+  workflowCatalog,
+  type WorkflowOverrides
+} from "../workflowModels"
 
 export class ExitError extends Error {
   constructor(readonly code: number) {
@@ -259,6 +264,65 @@ function printCatalog(ctx: Ctx, catalog: string): void {
   for (const line of catalog.split("\n")) ctx.services.logger.echo(line)
 }
 
+const WORKFLOW_FLAGS = {
+  "--model-orchestrator": "orchestrator",
+  "--model-reviewer": "reviewer",
+  "--model-implementer": "implementer",
+  "--review-min-score": "minimumScore",
+  "--review-max-rounds": "maxRounds"
+} as const satisfies Readonly<Record<string, keyof WorkflowOverrides>>
+
+function workflowUsage(ctx: Ctx): void {
+  printCatalog(ctx, workflowCatalog())
+  ctx.services.logger.echo("")
+  ctx.services.logger.echo("Workflow override flags:")
+  ctx.services.logger.echo("  --model-orchestrator=<profile:name|tool:model@effort>")
+  ctx.services.logger.echo("  --model-reviewer=<profile:name|tool:model@effort>")
+  ctx.services.logger.echo("  --model-implementer=<profile:name|tool:model@effort>")
+  ctx.services.logger.echo("  --review-min-score=<0..100>")
+  ctx.services.logger.echo("  --review-max-rounds=<1..10>")
+}
+
+export function parseWorkflowArgs(ctx: Ctx, args: ReadonlyArray<string>): WorkflowOverrides {
+  const overrides: Partial<Record<keyof WorkflowOverrides, string>> = {}
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] ?? ""
+    if (arg === "-h" || arg === "--help") {
+      workflowUsage(ctx)
+      throw new ExitError(0)
+    }
+
+    const equals = arg.indexOf("=")
+    const flag = equals === -1 ? arg : arg.slice(0, equals)
+    const key = WORKFLOW_FLAGS[flag as keyof typeof WORKFLOW_FLAGS]
+    if (key === undefined) throw new Error(`Unknown workflow arg: ${arg}`)
+
+    let value: string
+    if (equals !== -1) {
+      value = arg.slice(equals + 1)
+    } else {
+      const next = args[index + 1]
+      if (next === undefined || next.startsWith("--")) {
+        throw new Error(`${flag} requires a value: ${flag}=<value>`)
+      }
+      value = next
+      index += 1
+    }
+    if (value === "") throw new Error(`${flag} requires a value: ${flag}=<value>`)
+    overrides[key] = value
+  }
+
+  if (Object.keys(overrides).length === 0) {
+    throw new Error("At least one workflow override flag is required")
+  }
+  buildWorkflowRecord(overrides)
+  return overrides
+}
+
+export function printWorkflowUsage(ctx: Ctx): void {
+  workflowUsage(ctx)
+}
+
 export function validateModifierFlags(ctx: Ctx): void {
   const { err, warn } = ctx.services.logger
   const supplied = (flag: ModifierFlag, value: string): boolean =>

package/cli/src/engine-native/sessionRelayReadiness.ts

@@ -0,0 +1,94 @@
+import { spawnSync } from "node:child_process"
+
+import { isObject, parseJson } from "./jq"
+
+const SESSION_RELAY_PLUGIN_ID = "session-relay@docks"
+
+export type SessionRelayReadinessReason =
+  | "codex_cli_unavailable"
+  | "plugin_list_failed"
+  | "invalid_plugin_list"
+  | "plugin_missing"
+  | "plugin_ambiguous"
+  | "plugin_not_installed"
+  | "plugin_disabled"
+
+export interface SessionRelayReadiness {
+  readonly schema: 1
+  readonly state: "ready" | "unavailable"
+  readonly reason: SessionRelayReadinessReason | null
+  readonly version: string | null
+  readonly installed: boolean
+  readonly enabled: boolean
+  readonly scope: "new_sessions"
+}
+
+export interface CodexPluginListProbe {
+  readonly status: number | null
+  readonly stdout: string
+  readonly errorCode: string | null
+}
+
+function unavailable(
+  reason: SessionRelayReadinessReason,
+  fields: { version?: string | null; installed?: boolean; enabled?: boolean } = {}
+): SessionRelayReadiness {
+  return {
+    schema: 1,
+    state: "unavailable",
+    reason,
+    version: fields.version ?? null,
+    installed: fields.installed ?? false,
+    enabled: fields.enabled ?? false,
+    scope: "new_sessions"
+  }
+}
+
+export function classifySessionRelayReadiness(probe: CodexPluginListProbe): SessionRelayReadiness {
+  if (probe.errorCode === "ENOENT") return unavailable("codex_cli_unavailable")
+  if (probe.errorCode !== null || probe.status !== 0) return unavailable("plugin_list_failed")
+
+  const value = parseJson(probe.stdout)
+  if (value === undefined || !isObject(value) || !Array.isArray(value["installed"])) {
+    return unavailable("invalid_plugin_list")
+  }
+
+  const matches = value["installed"].filter(
+    (entry) => isObject(entry) && entry["pluginId"] === SESSION_RELAY_PLUGIN_ID
+  )
+  if (matches.length === 0) return unavailable("plugin_missing")
+  if (matches.length !== 1) return unavailable("plugin_ambiguous")
+
+  const row = matches[0]
+  if (row === undefined || !isObject(row)) return unavailable("invalid_plugin_list")
+  const version = row["version"]
+  const installed = row["installed"]
+  const enabled = row["enabled"]
+  if (typeof version !== "string" || version.length === 0 || typeof installed !== "boolean" || typeof enabled !== "boolean") {
+    return unavailable("invalid_plugin_list")
+  }
+  if (!installed) return unavailable("plugin_not_installed", { version, enabled })
+  if (!enabled) return unavailable("plugin_disabled", { version, installed })
+
+  return {
+    schema: 1,
+    state: "ready",
+    reason: null,
+    version,
+    installed,
+    enabled,
+    scope: "new_sessions"
+  }
+}
+
+export function sessionRelayReadiness(): SessionRelayReadiness {
+  const result = spawnSync("codex", ["plugin", "list", "--json"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  })
+  return classifySessionRelayReadiness({
+    status: result.status,
+    stdout: result.stdout ?? "",
+    errorCode: (result.error as NodeJS.ErrnoException | undefined)?.code ?? null
+  })
+}

package/cli/src/engine-native/workflowDeploy.ts

@@ -0,0 +1,139 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
+import { dirname } from "node:path"
+
+import type { Ctx } from "./index"
+import {
+  WORKFLOW_RECORD_PREFIX,
+  buildWorkflowRecord,
+  defaultWorkflowRecord,
+  parseWorkflowRecord,
+  renderWorkflowRecordLine,
+  type WorkflowOverrides,
+  type WorkflowRecordV1
+} from "../workflowModels"
+
+export interface WorkflowFileSystem {
+  readonly read: (path: string) => string | undefined
+  readonly writeAtomic: (path: string, bytes: string) => void
+  readonly remove: (path: string) => void
+}
+
+let atomicWriteSequence = 0
+
+const nodeFileSystem: WorkflowFileSystem = {
+  read: (path) => existsSync(path) ? readFileSync(path, "utf8") : undefined,
+  writeAtomic: (path, bytes) => {
+    mkdirSync(dirname(path), { recursive: true })
+    const temporary = `${path}.tmp-${process.pid}-${atomicWriteSequence++}`
+    try {
+      writeFileSync(temporary, bytes)
+      renameSync(temporary, path)
+    } finally {
+      rmSync(temporary, { force: true })
+    }
+  },
+  remove: (path) => rmSync(path, { force: true })
+}
+
+interface DocumentRecord {
+  readonly record: WorkflowRecordV1 | undefined
+  readonly line: string | undefined
+}
+
+function readDocumentRecord(document: string | undefined, label: string): DocumentRecord {
+  const lines = (document ?? "").split("\n").filter((line) => line.startsWith(WORKFLOW_RECORD_PREFIX))
+  if (lines.length === 0) return { record: undefined, line: undefined }
+
+  let canonicalLine: string | undefined
+  let canonicalRecord: WorkflowRecordV1 | undefined
+  for (const line of lines) {
+    let record: WorkflowRecordV1
+    try {
+      record = parseWorkflowRecord(JSON.parse(line.slice(WORKFLOW_RECORD_PREFIX.length)) as unknown)
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error)
+      throw new Error(`${label} contains a malformed Docks workflow record: ${detail}`)
+    }
+    const rendered = renderWorkflowRecordLine(record)
+    if (canonicalLine !== undefined && rendered !== canonicalLine) {
+      throw new Error(`${label} contains conflicting Docks workflow records`)
+    }
+    canonicalLine = rendered
+    canonicalRecord = record
+  }
+  return { record: canonicalRecord, line: canonicalLine }
+}
+
+export function upsertWorkflowRecord(document: string, record: WorkflowRecordV1): string {
+  const content = document
+    .split("\n")
+    .filter((line) => !line.startsWith(WORKFLOW_RECORD_PREFIX))
+    .join("\n")
+    .replace(/\n+$/, "")
+  const line = renderWorkflowRecordLine(record)
+  return content === "" ? `${line}\n` : `${content}\n${line}\n`
+}
+
+export function renderDefaultWorkflowInstructions(document: string): string {
+  readDocumentRecord(document, "SoT instruction document")
+  return upsertWorkflowRecord(document, defaultWorkflowRecord())
+}
+
+function restoreSnapshot(fileSystem: WorkflowFileSystem, path: string, snapshot: string | undefined): void {
+  if (snapshot === undefined) fileSystem.remove(path)
+  else fileSystem.writeAtomic(path, snapshot)
+}
+
+export function deployWorkflowOverrides(
+  ctx: Ctx,
+  overrides: WorkflowOverrides,
+  fileSystem: WorkflowFileSystem = nodeFileSystem
+): void {
+  const claudePath = `${ctx.home}/.claude/CLAUDE.md`
+  const codexPath = `${ctx.home}/.codex/AGENTS.md`
+  const claudeBefore = fileSystem.read(claudePath)
+  const codexBefore = fileSystem.read(codexPath)
+  const claudeState = readDocumentRecord(claudeBefore, claudePath)
+  const codexState = readDocumentRecord(codexBefore, codexPath)
+
+  if (claudeState.line !== undefined && codexState.line !== undefined && claudeState.line !== codexState.line) {
+    throw new Error("Claude and Codex instruction files contain conflicting Docks workflow records")
+  }
+
+  const base = claudeState.record ?? codexState.record ?? defaultWorkflowRecord()
+  const record = buildWorkflowRecord(overrides, base)
+  const claudeAfter = upsertWorkflowRecord(claudeBefore ?? "", record)
+  const codexAfter = upsertWorkflowRecord(codexBefore ?? "", record)
+  const claudeChanged = claudeBefore !== claudeAfter
+  const codexChanged = codexBefore !== codexAfter
+
+  if (ctx.dryRun) {
+    if (claudeChanged) ctx.services.logger.echo(`[dry-run] update Docks workflow record in ${claudePath}`)
+    if (codexChanged) ctx.services.logger.echo(`[dry-run] update Docks workflow record in ${codexPath}`)
+    if (!claudeChanged && !codexChanged) ctx.services.logger.verbose("Workflow models already match the requested state")
+    return
+  }
+
+  if (!claudeChanged && !codexChanged) {
+    ctx.services.logger.verbose("Workflow models already match the requested state")
+    return
+  }
+
+  try {
+    if (claudeChanged) fileSystem.writeAtomic(claudePath, claudeAfter)
+    if (codexChanged) fileSystem.writeAtomic(codexPath, codexAfter)
+  } catch (error) {
+    try {
+      restoreSnapshot(fileSystem, claudePath, claudeBefore)
+      restoreSnapshot(fileSystem, codexPath, codexBefore)
+    } finally {
+      ctx.services.logger.err("Workflow update failed; restored both instruction files to their pre-run state")
+    }
+    throw error
+  }
+
+  ctx.services.logger.change("Workflow models updated in Claude and Codex instructions")
+  ctx.services.logger.warn("Start fresh Claude Code and Codex sessions before relying on the new workflow roles")
+  ctx.nextStepTriggers.claudeRestart = true
+  ctx.nextStepTriggers.codexRestart = true
+}