maf 0.2.0 → 0.4.0

data/lib/maf/shared/harnesses/cursor.rb

@@ -3,6 +3,7 @@
 # maf shared library - code that the maf CLI and the scripts in .maf/bin share.
 # The installer copies this folder to .maf/lib/maf/shared/. maf update replaces it.
 # Use the Ruby stdlib only: a script loads this file without a gem bundle.
+require "open3"
 require_relative "../harness/traits"
 
 module Maf
@@ -37,7 +38,7 @@ module Maf
           name: <%= role %>
           description: <%= description %>
           <% if model -%>
-          model: <%= model %>
+          model: <%= Maf::Shared::Harnesses::CursorModels.name(model, effort) %>
           <% end -%>
           readonly: <%= !can_edit %>
           ---
@@ -45,20 +46,75 @@ module Maf
           <%= prompt %>
         ERB
 
-        def launch(role, model)
-          ["agent", *model_flag(model), "Read #{role_path(role)} and follow it exactly. Start your work loop now."]
+        def launch(role, model, effort = nil)
+          warn "maf: Cursor takes the level in the model name. Without a model, maf drops --effort." if effort && !model
+          ["agent", *model_flag(CursorModels.name(model, effort)),
+           "Read #{role_path(role)} and follow it exactly. Start your work loop now."]
         end
 
         # `agent -p --output-format json` prints one result object with session_id and result.
         def build_command(config, prompt, session_id)
-          %w[agent -p --output-format json --force --trust --approve-mcps] + model_flag(config.model) +
+          %w[agent -p --output-format json --force --trust
+             --approve-mcps] + model_flag(CursorModels.name(config.model, config.effort)) +
             resume(session_id, "--resume") + [first_prompt(config.role, prompt, session_id)]
         end
 
+        # Cursor has no effort flag. The level is a part of the model name, so
+        # maf lists each model without its level, and the levels of each model.
+        def models = CursorModels.bases
+
+        def known_model?(model, list = models)
+          list.nil? || list.include?(model) || CursorModels.listed.include?(model)
+        end
+
+        def efforts(model = nil) = CursorModels.efforts(model)
+        def effort_required?(model) = CursorModels.effort_required?(model)
+
         # A failed run prints no JSON, only an error on stderr. So a resume
         # without a result event and with "not found" is stale. Cursor reports no token usage.
         def stale_session?(output) = result_event(output).empty? && output.match?(/not found/i)
       end
+
+      # CursorModels reads `agent --list-models`. A name is BASE-LEVEL or
+      # BASE-LEVEL-fast, for example gpt-5.3-codex-high-fast.
+      module CursorModels
+        LEVELS = %w[low medium high xhigh max].freeze
+        LEVEL = /-(#{LEVELS.join("|")})(?=(?:-fast)?\z)/
+
+        def self.listed
+          return @listed if defined?(@listed)
+
+          @listed = read
+        end
+
+        def self.read
+          out, status = Open3.capture2("agent", "--list-models", err: File::NULL)
+          status.success? ? out.scan(/^(\S+) - /).flatten : nil
+        rescue SystemCallError
+          nil
+        end
+
+        def self.bases = listed&.map { |model| model.sub(LEVEL, "") }&.uniq
+
+        # nil: maf cannot read the list. A name with a level takes no other level.
+        def self.efforts(model)
+          return nil unless listed
+          return [] if model.nil? || (model.match?(LEVEL) && listed.include?(model))
+
+          LEVELS.select { |level| listed.include?(name(model, level)) }
+        end
+
+        # A base that Cursor does not list by itself runs only with a level.
+        def self.effort_required?(model) = !listed.nil? && !listed.include?(model) && !efforts(model).to_a.empty?
+
+        # A name with a level gets the new level instead.
+        def self.name(model, effort)
+          return model unless model && effort
+
+          model = model.sub(LEVEL, "")
+          model.end_with?("-fast") ? model.sub(/-fast\z/, "-#{effort}-fast") : "#{model}-#{effort}"
+        end
+      end
     end
   end
 end

data/lib/maf/shared/harnesses/hermes.rb

@@ -13,16 +13,14 @@ module Maf
       # outside the project. `--skills <project>-<role>` loads one. Hermes has
       # no agent flag and cannot be woken, so an idle agent blocks in
       # `coord next --wait`. A role with can_edit false starts without the
-      # file-writing toolsets. Hermes keeps hooks and MCP servers in global
+      # file-writing toolsets. No role gets the kanban or delegation
+      # toolset. Hermes keeps hooks and MCP servers in global
       # files, so maf prints the commands that add them.
       class Hermes < Harness::Base
         include Harness::ResultEvent
 
         DEFAULT_DIR = File.join(Dir.home, ".hermes", "skills")
         MAX_TURNS = 50
-        # Stop Hermes before the dispatcher kills it, so it can still write its
-        # result event. NOTE: assets/dispatcher Spawn::GRACE.
-        KILL_GRACE = 5
 
         def sandbox_dirs = [File.join(Dir.home, ".hermes")]
         PROTECTED = %w[config.yaml .env shell_init.sh SOUL.md hooks agent-hooks shell-hooks-allowlist.json bin scripts
@@ -56,8 +54,11 @@ module Maf
         ERB
 
         def model_hint(_model) = "hermes model"
+        EFFORTS = %w[none minimal low medium high xhigh max ultra].freeze
+        def efforts(_model = nil) = EFFORTS
+        def effort_flag(effort) = super(effort, "--reasoning")
         def mcp_command(server, vault) = "hermes mcp add #{server} --command ruby --args #{vault} mcp"
-        def install_hooks(_project) = Flow::HermesHookSetup.new.install
+        def install_hooks(_project) = Flow::HermesHookSetup.new.install | Flow::HermesEnvSetup.new.install
         def global_files = [File.join(Dir.home, ".hermes", "agent-hooks", "next-task.sh")]
 
         # The skill name uses the main checkout's name, from the project root
@@ -74,7 +75,11 @@ module Maf
           Project.manifest.fetch("agents", []).any? { |agent| agent["role"] == role && agent["can_edit"] == false }
         end
 
-        def tools(role) = read_only?(role) ? ["-t", Roles::READ_ONLY_TOOLSETS] : []
+        # With -t, Hermes loads an MCP server only when the list names its toolset.
+        def tools(role)
+          toolsets = read_only?(role) ? Roles::READ_ONLY_TOOLSETS : Roles::EDIT_TOOLSETS
+          ["-t", "#{toolsets},mcp-graphify-#{File.basename(Project.root)}"]
+        end
 
         PROMPT = "Follow the coordination rules of your role skill as role %<role>s. " \
                  "Run coord inbox, then coord next --wait. Claim a task, do the work, finish it. Repeat."
@@ -82,10 +87,10 @@ module Maf
                       "You are a lead role. Never claim a task. Run coord inbox --wait and handle each message."
 
         # `-q` on a TTY seeds an interactive session with the prompt.
-        def launch(role, model)
+        def launch(role, model, effort = nil)
           prompt = format(Roles::LEADS.include?(role) ? LEAD_PROMPT : PROMPT, role: role)
-          ["hermes", "chat", *skill(role)&.then { |name| ["--skills", name] }, *model_flag(model), *tools(role),
-           "-q", prompt]
+          ["hermes", "chat", *skill(role)&.then { |name| ["--skills", name] }, *model_flag(model), *effort_flag(effort),
+           *tools(role), "-q", prompt]
         end
 
         # --no-skill drops the skill. Without --skill, the generated skill of the role loads.
@@ -99,11 +104,16 @@ module Maf
         # `hermes chat --oneshot` with JSONL output and the skill preloaded.
         def build_command(config, prompt, session_id)
           cmd = %w[hermes chat --oneshot --yolo --format stream-json -Q]
-          cmd += [*(["--skills", config.skill] if config.skill), *model_flag(config.model), *tools(config.role)]
-          cmd += ["--max-turns", config.max_turns.to_s, "--run-budget", [config.timeout - KILL_GRACE, 1].max.to_s]
+          cmd += run_flags(config)
+          cmd += ["--max-turns", config.max_turns.to_s]
           cmd + resume(session_id, "--resume") + ["-q", prompt]
         end
 
+        def run_flags(config)
+          [*(["--skills", config.skill] if config.skill), *model_flag(config.model), *effort_flag(config.effort),
+           *tools(config.role)]
+        end
+
         def stale_session?(output) = output.include?("Session not found")
         def result_text(output) = result_event(output)["text"]
       end

data/lib/maf/shared/harnesses/opencode.rb

@@ -37,6 +37,9 @@ module Maf
           <% if model -%>
           model: <%= model %>
           <% end -%>
+          <% if effort -%>
+          variant: <%= effort %>
+          <% end -%>
           temperature: 0.1
           permission:
             edit: <%= can_edit ? "allow" : "deny" %>
@@ -92,15 +95,19 @@ module Maf
         def run_env(config) = config_env(run_file(config, "mcp", "opencode.json"))
         def config_env(file) = File.exist?(file) ? { "OPENCODE_CONFIG" => file } : {}
 
-        def launch(role, model)
+        # The TUI has no variant flag. It reads the variant from the agent file.
+        def launch(role, model, effort = nil)
+          OpencodeVariant.warn_unused(File.join(role_dir, "#{role}.md"), role, effort)
           ["opencode", ".", "--agent", role, "--prompt", "Start your work loop now.", *model_flag(model)]
         end
 
+        def effort_flag(effort) = super(effort, "--variant")
+
         # `opencode run --format json`. The result event shape is not verified,
         # so the log shows no result text.
         def build_command(config, prompt, session_id)
           %w[opencode run --format json --agent] + [config.role] + model_flag(config.model, "-m") +
-            resume(session_id, "--session") + [prompt]
+            effort_flag(config.effort) + resume(session_id, "--session") + [prompt]
         end
 
         # DeepSeek costs twice as much at peak hours.
@@ -164,6 +171,22 @@ module Maf
             "and json_extract(data,'$.type') = 'tool'"
         end
       end
+
+      # OpencodeVariant tells the user how to change the level of an interactive session.
+      module OpencodeVariant
+        PATTERN = /\A---\n(?:(?!^---$).)*?^variant:\s*(\S+)/m
+        HINT = "maf: the opencode TUI cannot take --effort %<effort>s. The session starts with %<current>s. " \
+               "In the session, press ctrl+t to pick the variant %<effort>s. If the agent is in its work " \
+               "loop, stop it (Esc) and restart the loop: \"Start your work loop now.\" " \
+               "To keep the level for each session: maf add opencode:%<role>s --effort %<role>s=%<effort>s"
+
+        def self.warn_unused(path, role, effort)
+          current = File.exist?(path) ? File.read(path)[PATTERN, 1] : nil
+          return if effort.nil? || effort == current
+
+          warn format(HINT, effort: effort, role: role, current: current ? "variant #{current}" : "the default variant")
+        end
+      end
     end
   end
 end

data/lib/maf/shared/roles.rb

@@ -14,6 +14,10 @@ module Maf
       # Hermes toolsets for a role with can_edit false: no file, code_execution,
       # or delegation toolset. The shell stays, because the role needs coord and git.
       READ_ONLY_TOOLSETS = "terminal,web,skills,todo,memory,session_search,clarify"
+
+      # Hermes toolsets for a role that edits. coord is the only task board and
+      # maf starts the workers, so kanban, delegation, and cronjob stay off.
+      EDIT_TOOLSETS = "#{READ_ONLY_TOOLSETS},file,code_execution,browser,vision".freeze
     end
   end
 end

data/lib/maf/shared/sandbox/seatbelt.rb

@@ -11,6 +11,7 @@ module Maf
       # Seatbelt runs a command in a macOS sandbox-exec profile.
       module Seatbelt
         COMMAND = "/usr/bin/sandbox-exec"
+        MARKER = "MAF_SEATBELT"
         DEVICES = '(literal "/dev/null") (literal "/dev/zero") (literal "/dev/dtracehelper") ' \
                   '(regex #"^/dev/tty") (regex #"^/dev/fd/") (regex #"^/dev/ptmx")'
         DNS = '(path-literal "/private/var/run/mDNSResponder")'
@@ -20,9 +21,12 @@ module Maf
 
         def self.wrap(cmd, paths)
           tmp = private_tmp(paths.root)
-          [COMMAND, "-p", profile(paths, tmp), "env", "TMPDIR=#{tmp}/", "XDG_CACHE_HOME=#{tmp}/cache", *cmd]
+          [COMMAND, "-p", profile(paths, tmp), "env", "#{MARKER}=1", "TMPDIR=#{tmp}/", "XDG_CACHE_HOME=#{tmp}/cache",
+           *cmd]
         end
 
+        def self.inside? = ENV[MARKER] == "1"
+
         def self.available? = File.executable?(COMMAND)
         def self.require! = available? || abort("maf: sandbox mode seatbelt needs #{COMMAND} (macOS only).")
 

data/lib/maf/shared/sandbox.rb

@@ -18,6 +18,8 @@ module Maf
       BACKENDS = { "seatbelt" => Seatbelt, "bwrap" => Bwrap }.freeze
       MODES = ["off", "auto", *BACKENDS.keys].freeze
       POLICY = File.join(".maf", "sandbox.json")
+      NESTED = "maf: this process runs in the macOS sandbox, and macOS cannot start a second sandbox in it. " \
+               "Start the worker from your terminal: cd <worktree> && maf start"
 
       def self.policy
         path = File.join(Project.root, POLICY)
@@ -40,9 +42,13 @@ module Maf
       def self.wrap(cmd, harness, coord_dir: ENV.fetch("COORD_DIR", nil))
         policy = self.policy
         mode = mode(policy)
+        refuse_nested!(mode)
         mode == "off" ? cmd : BACKENDS[mode].wrap(harness.sandboxed(cmd), paths(harness, policy, coord_dir))
       end
 
+      def self.nested?(mode = self.mode) = mode == "seatbelt" && Seatbelt.inside?
+      def self.refuse_nested!(mode = self.mode) = nested?(mode) && abort(NESTED)
+
       def self.keeping_links(harness, coord_dir: ENV.fetch("COORD_DIR", nil))
         links = protected_links(harness, coord_dir)
         yield

data/lib/maf/team.rb

@@ -2,7 +2,7 @@
 
 # team.rb - add, replace, and retire workers in one command.
 #
-#   maf prepare HARNESS ROLE[_WORKER] [--model M] [--dispatch | --interactive] [--replace WORKER]
+#   maf prepare HARNESS ROLE[_WORKER] [--model M] [--effort L] [--dispatch | --interactive] [--replace WORKER]
 #   maf retire WORKER
 #
 # The project manager runs these commands. `maf prepare` adds the role file,
@@ -24,6 +24,7 @@ module Maf
     end
 
     def self.notify(root, text) = coord(root, "msg", "--from", "maf", "architect", text)
+    def self.agent? = !ENV["COORD_ROLE"].to_s.empty?
   end
 
   # Prepare makes a worker ready to start. With --replace, it retires the
@@ -35,6 +36,8 @@ module Maf
     # The architect never talks to the user. A dispatched architect gets fresh
     # sessions with a handoff note, so its context stays small.
     DISPATCH_DEFAULT = %w[architect].freeze
+    NO_BUDGET = "maf: an agent cannot change the team without a budget. Ask the user to set one " \
+                "(maf team set --max N), or to run this command in a terminal."
 
     def self.mode_args(argv)
       return argv - ["--interactive"] if argv.include?("--interactive")
@@ -52,7 +55,7 @@ module Maf
     end
 
     def run
-      @budget.check!(@args.harness, @args.model, @budget.count(workers_after))
+      check_budget
       retire = (Retire.new(@root, @replace).tap(&:check!) if @replace)
       Dir.chdir(@root) { prepare }
       retire.run if retire && Workers.id(@replace) != @args.worker
@@ -61,18 +64,23 @@ module Maf
 
     def announce
       Team.notify(@root, "Team change: worker #{@args.worker} (#{@args.harness}) joined as #{@args.role}.")
-      @args.dispatch ? start_dispatcher : print_next_steps
+      @args.dispatch && !Shared::Sandbox.nested? ? start_dispatcher : print_next_steps
     end
 
     private
 
+    def check_budget
+      abort NO_BUDGET if Team.agent? && !@budget.limited?
+      @budget.check!(@args.harness, @args.model, @budget.count(workers_after))
+    end
+
     def take_replace(argv)
       index = argv.index("--replace") or return nil
       argv.slice!(index, 2)[1] || abort("maf: --replace needs a worker, for example backend-developer_2")
     end
 
     def prepare
-      Maf.flow("--agent", spec) unless Maf.agent_specs.include?("#{@args.harness}:#{@args.role}")
+      Maf.flow("--agent", spec, *effort_flag) unless Maf.agent_specs.include?("#{@args.harness}:#{@args.role}")
       worktree = SetupAgent::Worktree.ensure(@args.role, @args.worker_id, @args.harness)
       SetupAgent::RoleFile.copy(@root, worktree.dir, @args.harness, @args.role)
       archive_on_harness_change
@@ -87,6 +95,7 @@ module Maf
     end
 
     def spec = [@args.harness, @args.role, @args.model].compact.join(":")
+    def effort_flag = @args.effort ? ["--effort", "#{@args.role}=#{@args.effort}"] : []
 
     def workers_after
       all = Workers.at(@root).all
@@ -98,12 +107,12 @@ module Maf
     def start_dispatcher
       Dir.chdir(@root)
       args = [@args.harness, "#{@args.role}_#{@args.worker_id}", "--dispatch", "--detach"]
-      SetupAgent.run(@args.model ? args + ["--model", @args.model] : args)
+      SetupAgent.run(args + { "--model" => @args.model, "--effort" => @args.effort }.compact.flatten)
     end
 
     def entry(dir)
       { "role" => @args.role, "worker_id" => @args.worker_id, "harness" => @args.harness,
-        "model" => @args.model, "dispatch" => @args.dispatch, "dir" => dir }.compact
+        "model" => @args.model, "effort" => @args.effort, "dispatch" => @args.dispatch, "dir" => dir }.compact
     end
 
     def print_next_steps

data/lib/maf/team_command.rb

@@ -18,7 +18,14 @@ module Maf
       @root = root
     end
 
-    def run = @argv.first == "set" ? set(@argv.drop(1)) : show
+    AGENT_SET = "maf: only the user sets the team budget. Give the user this command to run in a terminal."
+
+    def run
+      return show unless @argv.first == "set"
+
+      abort AGENT_SET if Team.agent?
+      set(@argv.drop(1))
+    end
 
     private
 
@@ -32,10 +39,12 @@ module Maf
 
     def line(id, entry)
       mode = entry["dispatch"] ? "dispatch" : "interactive"
-      [id.ljust(28), entry["role"].to_s.ljust(20), entry["harness"], entry["model"] || "-", mode, state(id, entry)]
+      [id.ljust(28), entry["role"].to_s.ljust(20), entry["harness"], model(entry), mode, state(id, entry)]
         .join("  ")
     end
 
+    def model(entry) = [entry["model"] || "-", entry["effort"]].compact.join("/")
+
     def state(id, entry)
       pid = entry["pid"]
       return "-" unless pid

data/lib/maf/untrack.rb

@@ -18,6 +18,15 @@ module Maf
       @yes = argv.include?("--yes")
     end
 
+    TRACKED = "maf: git tracks files of the flow. Each maf update changes them in every worktree, " \
+              "and coord start-task refuses a dirty worktree. Run maf untrack --check, then maf untrack, then commit."
+
+    def self.warn_tracked(root) = (warn TRACKED unless new(root, []).tracked.empty?)
+
+    DONE = ["", "The flow left git. Review the change with `git status`, then commit it.",
+            "A branch that still tracks the flow files can delete them in a checkout or a merge.",
+            "maf keeps a backup of the flow config in .git/maf/backup. Run `maf restore` to put it back."].freeze
+
     def run
       steps = plan
       return puts("maf: git tracks no file of the flow in #{@root}.") if steps.empty?
@@ -50,7 +59,7 @@ module Maf
       abort "maf: cancelled" unless @yes || confirmed?
       steps.each(&:run)
       Dir.chdir(@root) { Maf.flow }
-      puts "", "The flow left git. Review the change with `git status`, then commit it."
+      puts DONE
     end
 
     def confirmed?
@@ -58,6 +67,8 @@ module Maf
       $stdin.gets.to_s.strip.match?(/\Ay(es)?\z/i)
     end
 
+    public
+
     # The tracked files of .maf/, and the tracked paths of each harness (Harness#untrack_paths).
     def tracked
       harness_paths = Maf::Shared::Harness.all.flat_map { |harness| harness.untrack_paths(@root, method(:git_files)) }

data/lib/maf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Maf
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/maf/worker_control.rb

@@ -26,7 +26,7 @@ module Maf
       @root = root
       @force = force
       @limits = limits
-      @worker = Workers.id(spec)
+      @worker = resolve(Workers.at(root).all, Workers.id(spec))
       @entry = Workers.at(root).find(@worker) || abort("maf: no worker #{@worker}")
     end
 
@@ -39,6 +39,17 @@ module Maf
 
     private
 
+    def resolve(workers, worker)
+      return worker if workers.key?(worker)
+
+      only_worker(worker, workers.select { |_, entry| entry["role"] == worker }.keys) || worker
+    end
+
+    def only_worker(role, names)
+      abort "maf: role #{role} has more than one worker: #{names.join(", ")}. Name one." if names.size > 1
+      names.first
+    end
+
     def status = puts("#{@worker}: #{live? ? "running (pid #{pid})" : "stopped"}")
 
     def stop

data/lib/maf/worker_list.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# worker_list.rb - list the workers that run now: sessions and dispatchers.
+require "json"
+require "time"
+require_relative "workers"
+require_relative "shared/processes"
+
+module Maf
+  # WorkerList shows each running worker process of the project. A worker
+  # can run twice, for example as a session and as a dispatcher.
+  class WorkerList
+    Row = Struct.new(:worker, :role, :harness, :mode, :pid, :started)
+    HEADER = %w[WORKER ROLE HARNESS MODE PID STARTED].freeze
+    LSTART = "%a %b %d %H:%M:%S %Y %z"
+
+    def initialize(root)
+      @root = root
+      @workers = Workers.at(root)
+    end
+
+    def run
+      rows = running
+      puts rows.empty? ? "No worker runs." : table([HEADER] + rows.map { |row| row.to_a.map(&:to_s) }), warnings(rows)
+    end
+
+    private
+
+    def running = (sessions + dispatchers + registered).uniq(&:pid).sort_by { |row| [row.worker, row.mode] }
+
+    def coord_dir = File.join(@root, ".maf", "coordination")
+    def records(dir, pattern) = Dir.glob(File.join(coord_dir, dir, pattern)).map { |path| [path, read(path)] }
+
+    def sessions
+      records("sessions", "*.maf.json").filter_map do |path, record|
+        row(record, "session") if session_live?(record["pid"], File.mtime(path))
+      end
+    end
+
+    def session_live?(pid, registered)
+      started = Shared::Processes.started_at(pid)
+      Shared::Processes.alive?(pid) && !started.empty? && Time.strptime("#{started} +0000", LSTART) <= registered
+    rescue ArgumentError
+      false
+    end
+
+    def dispatchers
+      records("presence", "*.json").filter_map do |_, entry|
+        row(entry, "dispatch") if entry["mode"] == "dispatch" && Shared::Processes.live?(entry)
+      end
+    end
+
+    def registered
+      @workers.all.filter_map do |worker, entry|
+        row(entry.merge("worker" => worker), "dispatch") if @workers.dispatcher?(worker)
+      end
+    end
+
+    def row(data, mode)
+      entry = @workers.find(data["worker"]).to_h
+      Row.new(data["worker"], data["role"] || entry["role"], data["harness"] || entry["harness"], mode,
+              data["pid"].to_i, Shared::Processes.started_at(data["pid"]))
+    end
+
+    def table(lines)
+      widths = lines.transpose.map { |column| column.map(&:size).max }
+      lines.map { |line| line.zip(widths).map { |text, width| text.ljust(width) }.join("  ").rstrip }
+    end
+
+    def warnings(rows)
+      twice = rows.group_by(&:worker).select { |_, list| list.size > 1 }
+      stopped = @workers.all.keys - rows.map(&:worker)
+      twice.map { |worker, list| "warning: #{worker} runs #{list.size} times (pids #{list.map(&:pid).join(", ")})" } +
+        (stopped.empty? ? [] : ["stopped: #{stopped.join(", ")}"])
+    end
+
+    def read(path)
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError, SystemCallError
+      {}
+    end
+  end
+end

data/templates/roles.yml

@@ -4,6 +4,9 @@
 # the model with --model ROLE=MODEL. If the user does not choose a model,
 # claude roles get lib/maf/flow.rb's DEFAULT_MODELS entry (claude-opus-5-5).
 #
+# `effort` is the default effort level. A role gets it when the harness lists
+# the level. --effort ROLE=LEVEL overrides it. A lower level uses fewer tokens.
+#
 # `description` is also the routing line in the architect's "Available roles"
 # list. Keep it short and specific to the role.
 #
@@ -42,6 +45,7 @@ roles:
       - If a message starts with "ESCALATION", a role cannot fix a problem. Tell the user in plain words:
         what failed, which task, and the impact. Give two or three options with a recommended one.
         Wait for the answer. Then send the answer to the role with `coord msg`.
+        If the escalation names a blocked task, run `coord unblock <id>` after you send the answer.
       - If the architect escalates a repeated review failure, forward the
         options to the user. Do not send a new goal until the user decides.
 
@@ -53,6 +57,7 @@ roles:
       - Process detail in reports. The user needs outcomes and decisions.
       - Optimistic status. Report blockers and failed checks as they are.
     model_hint: "Strongest reasoning and long context, conversational. Cloud: Claude Opus 5.5 (default for the claude harness), GPT-5.x."
+    effort: medium
     can_edit: false
 
   architect:
@@ -84,6 +89,8 @@ roles:
         Goal, Inputs, Out of scope, Acceptance, Report format.
         A worker drifts if a field is missing.
       - Write acceptance criteria as exact test files or commands. The worker runs each one before coord done.
+      - A message `BLOCKED task <id> (dependency)` waits for other work. Plan or order that work.
+        When it lands, run `coord unblock <id>`. A blocked task stays out of `coord next` until then.
       - If a review rejects the same kind of problem two times, stop the fix
         loop. Send the project manager two or three options with the cost of
         each option. A third patch of the same kind usually fails too.
@@ -96,6 +103,7 @@ roles:
       - Code in task specs. Describe behavior and constraints instead.
       - Trust in a worker report without a diff check.
     model_hint: "Strongest reasoning and long context. Cloud: Claude Opus 5.5 (default for the claude harness), GPT-5.x, deepseek-v4."
+    effort: high
     can_edit: false
 
   backend-developer:
@@ -123,6 +131,7 @@ roles:
       - Edits to a test that looks wrong. Report the test to the architect.
       - Claims about code that you did not read.
     model_hint: "A strong code model. A local Qwen3.8-27B is enough for well-scoped tasks; use a cloud coder for hard or large changes."
+    effort: medium
     can_edit: true
 
   frontend-developer:
@@ -149,6 +158,7 @@ roles:
       - Values that are hard-coded to make a test pass.
       - Visual changes outside the task scope.
     model_hint: "Same as backend-developer: local coder for scoped work, cloud coder for hard UI work."
+    effort: medium
     can_edit: true
 
   tester:
@@ -174,6 +184,7 @@ roles:
       - Assertions that only repeat the implementation.
       - Deleted or weakened tests. A test removal needs architect approval.
     model_hint: "Mechanical test work usually fits a local coder model; use cloud for subtle failure analysis."
+    effort: low
     can_edit: true
 
   reviewer:
@@ -216,6 +227,7 @@ roles:
       - Style comments that the project's linter already covers.
       - A warning or minor finding labeled critical to force another round.
     model_hint: "Judgment-heavy. Prefer a cloud model with strong review ability."
+    effort: high
     can_edit: false
 
   skeptic:
@@ -252,6 +264,7 @@ roles:
       - A warning or minor finding labeled critical to force another round.
       - Style comments. The reviewer and the linter cover style.
     model_hint: "Judgment-heavy. Use a different model family from reviewer and auditor, for example GPT-5.x if reviewer runs Claude. Different models miss different defects."
+    effort: high
     can_edit: false
 
   auditor:
@@ -286,4 +299,5 @@ roles:
       - A warning or minor finding labeled critical to force another round.
       - Style comments. The reviewer and the linter cover style.
     model_hint: "Judgment-heavy. Use a different model family from reviewer and skeptic, for example Gemini, Grok, or a strong local model. Different models miss different defects."
+    effort: high
     can_edit: false