maf 0.1.0

data/lib/maf/flow/prompt_text.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # Prompt text that the role files embed.
+    # Applies to every `coord msg`, `coord annotate`, and task title/scope an
+    # agent writes. Generated role files ship standalone (opencode/codex/hermes
+    # sessions never see the user's own CLAUDE.md), so the rules are spelled
+    # out here instead of referenced.
+    STE_RULE = <<~TEXT.strip
+      - Write `coord msg`, `coord annotate`, and task titles in Simplified
+        Technical English: one instruction per sentence, active voice, name the
+        subject, max 20 words per sentence, no idioms.
+    TEXT
+
+    # Current Claude models start subagents readily and verify their own work
+    # without a prompt. Each subagent adds cost and time, so keep the use small.
+    SUBAGENT_RULE = <<~TEXT.strip
+      - Do the work yourself. Start a subagent only for a large, independent
+        search that you cannot finish in a few tool calls.
+      - Do not use subagents to verify your work.
+    TEXT
+
+    # Harnesses with a watcher that wakes an idle session.
+    WAKE_HARNESSES = %w[claude opencode].freeze
+    NO_TASK_STOP = "- If no task and no message is available, stop. The board watcher wakes you when work arrives.\n" \
+                   "  Do not wait in a loop: each return of a wait costs one model call."
+    NO_TASK_WAIT = <<~TEXT.strip
+      - If no task is available, run `coord next --wait --timeout 540`. It returns
+        when a task or a message arrives. If it times out, run it again. Do not poll by hand.
+    TEXT
+    # Codex returns a long tool call to the model about every 30 seconds, so a
+    # wait inside a tool call costs one model call per return. `coord await`
+    # arms the stop hook, and the hook waits outside the model.
+    NO_TASK_AWAIT = <<~TEXT.strip
+      - If no task and no message is available, run `coord await`. Then end your turn.
+        The stop hook waits for work and wakes you. Do not wait in a loop.
+    TEXT
+
+    # The project manager waits for reports. Each check in a loop sends the
+    # whole context again, so the wait must not call the model.
+    PM_WAIT = {
+      "claude" => "End your turn to wait for reports. The board watcher wakes you when a message arrives.",
+      "opencode" => "End your turn to wait for reports. The board watcher wakes you when a message arrives.",
+      "codex" => "To wait for reports, run `coord await`. Tell the user that you wait. Then end your turn.\n" \
+                 "   The stop hook wakes you when a message arrives."
+    }.freeze
+    PM_WAIT_DEFAULT = "Wait for reports with `coord inbox project-manager --wait --timeout 540`."
+
+    # Every role except the project manager reads the code graph before work.
+    # A query output stays in the context for each later call, so the budget is small.
+    GRAPH_RULE = <<~TEXT.strip
+      - Query the shared knowledge graph when you start a task or plan a goal, not before.
+        It finds code and prior decisions faster than grep. Run `vault age` first.
+        Then run `graphify query "..." --budget 800`, or use the graphify MCP tools. Never run `graphify export`.
+        Put one line in the report of that task or plan: "Graph: fresh", "Graph: stale", or "Graph: missing".
+    TEXT
+
+    # Only Claude Code has ScheduleWakeup. Other harnesses never see this rule.
+    CLAUDE_ARCHITECT_RULE = "- Never call ScheduleWakeup with `stop:false` and no `prompt`. " \
+                            "The call fails. Poll worker status through the task tool instead."
+
+    # The coordination contract that every role shares. It lives in the role
+    # prompt, not in the project's AGENTS.md: only a session that maf starts
+    # needs it, and the project keeps no trace of the tool.
+    CONTRACT = File.read(File.join(__dir__, "..", "..", "..", "assets", "agents-contract.md"))
+                   .lines.grep_v(/(>>>|<<<) multi-agent-flow/)
+                   .join.strip
+
+    DECISIONS = "the decisions folder: `.agent/decisions/` if it exists, else `docs/decisions/`"
+
+    # Lead roles cannot commit (ADR 0004). A worker commits their decision records.
+    ARCHITECT_DECISIONS = "Record decisions in #{DECISIONS}. " \
+                          "Create a task for a worker that can edit files. Put the decision text in the task."
+    PM_DECISIONS = "Write each decision to `$COORD_DIR/artifacts/<goal>/decision-<name>.md`. You cannot commit. " \
+                   "Send the path to the architect. The architect has a worker commit it in #{DECISIONS}."
+
+    WORKER_LOOP = <<~LOOP
+      Work loop:
+      1. Read messages: `coord inbox`.
+      2. List unclaimed tasks for your role: `coord next`.
+      3. Claim one: `coord claim <id>`.
+      4. Check out the task branch: `coord start-task <id>`. It starts from the goal branch.
+         Read the task spec: `coord show <id>`. Never use raw `task`.
+      5. Do the work. Stay inside the task scope.
+      6. Before any local model generation: `coord with-lock ollama -- <command>`.
+      7. If the task has a goal, merge the goal branch into the task branch: `git merge goal/<goal-short-id>`.
+         Then run the task tests. Do not run the merge suite.
+         Run each test file and command of the Acceptance field. Put each result in the TESTS line.
+         `coord done` refuses a task branch that lacks the goal branch head.
+      8. Commit the work on the task branch. The architect lands the task branch as one squash commit.
+      9. Report. If the task spec has a Report format, use it. Otherwise use:
+           coord annotate <id> "STATUS: done or blocked. FILES: <paths>. TESTS: <one-line result>. NOTES: <assumptions or risks>"
+      10. Finish: `coord done <id>`. The command sends a message to the architect.
+
+      Rules:
+      - You are one worker in a role pool. COORD_WORKER identifies you.
+      - One writer per path. Never edit outside the task scope.
+      - Do not create tasks. Ask the architect: `coord msg --from %{role} architect "<text>"`.
+      - If a problem is outside your task and you cannot fix it, escalate: `coord escalate --task <id> "<text>"`.
+        Examples: a missing tool, no access, a refused guard, rules that contradict.
+        The project manager asks the user and answers you. Then stop. Do not retry.
+      - Before you continue a claimed task after a pause, run `coord show <id>`. If the status is not pending,
+        or the worker is not you, stop work on that task. `coord reap` releases the claims of stalled workers.
+      - Finish the whole task. Report done only when each acceptance criterion passes.
+      - If you cannot finish, do the parts you can. Keep the claim, so another worker
+        does not hit the same blocker. Annotate the blocker and the missing parts.
+        Message the architect. Stop. Do not retry a failing approach.
+      %{no_task_instruction}
+      - Record durable knowledge in the shared vault or #{DECISIONS}.
+      - Never write ad-hoc verification scripts. The test suite is the verification.
+      #{GRAPH_RULE}
+      #{STE_RULE}
+      #{SUBAGENT_RULE}
+    LOOP
+
+    # Steps 2 to 9 are the same with and without a project manager.
+    ARCHITECT_GOAL_STEPS = <<~TEXT.strip
+      2. Decompose the goal into tasks. Keep scopes disjoint (one writer per path).
+         Compare the plan with the other open goals: `coord goal list`. List the shared schema and the shared files.
+         If two goals need the same change (for example one migration), move it into a small foundation goal.
+         The foundation goal merges first. The other goals start after it.
+      3. Create each task with the goal id, then add its spec:
+           coord add --role <role> --scope "<paths>" --goal <goal-id> --title "<title>"
+           coord annotate <id> "Goal: <goal>. Inputs: <files or context>. Out of scope: <paths or work>. Acceptance: <exact test files or commands that must pass>. Report format: <what to annotate>."
+      4. Watch progress: `coord goal show <goal-id>`, `coord conflicts`, `coord inbox architect`.
+         Each done task sends you a message. A task for a role without a worker alerts the project manager.
+      5. Answer worker questions. Resolve conflicts.
+      6. Before you trust a done task, inspect its diff and its TESTS line:
+         `git diff goal/<goal-short-id>...task/<task-short-id>`. Do not rerun the task tests.
+         If something is wrong, open a new task for the fix. Name the old task branch in Inputs.
+         Save the reason: `coord lesson <task-id> dead_end "<what failed>"` or `corrected "<the right way>"`.
+         For a done review task, open the file and line of each critical finding before you act.
+         If the cited file does not exist, drop the finding. A file that the plan creates is not a reason to drop.
+         Open fix tasks only for critical findings. Put warnings and minor findings into later task specs as notes.
+         If two reviews contradict, put the finding that you followed and the reason in your goal report.
+      7. Land each accepted task: `coord land <task-id> --subject "<type>(<area>): <summary>"`.
+         The command squashes the task branch into the goal branch as one commit and deletes the task branch.
+         Use a Conventional Commits subject. If the command reports a conflict, open a fix task.
+      8. When every task of the goal is landed, run `coord goal sync <goal-id>`. It merges the base branch into the goal.
+         If the sync conflicts, open a fix task. Then check the graph with `vault age`. Put its state in your report.
+         Then run the merge suite one time in the goal worktree:
+         `coord with-lock system-test -- <merge suite command>`. Source its `.maf/env.sh` first.
+      9. If `.maf/config.json` has a `github` section, run `coord goal pr <goal-id>`. Keep the goal open.
+         The command pushes the goal branch and opens the pull request for the user's review.
+         Each review arrives as a message. Fix each point with a fix task. Land it. Then run `coord goal pr` again.
+         After the merge, coord closes the goal and runs `coord gc --yes`.
+         Without a `github` section, close the goal: `coord goal done <goal-id>`. The user opens the pull request
+         from goal/<goal-short-id> into the base branch. After the merge, run `coord gc --yes`.
+         A goal pull request uses a merge commit, never a squash.
+    TEXT
+
+    ARCHITECT_RULES = <<~TEXT.strip
+      - Never edit files directly. Dispatch work.
+      - Change a goal branch only with `coord land` and `coord goal sync`. Never run `git merge` or `git commit` on it.
+      - Start each goal from the base branch. Never start a goal from another goal branch.
+      - Take the `ollama` lock only if you run a local model yourself.
+      - Hand work between stages with artifacts: `$COORD_DIR/artifacts/<goal>/<name>.md`.
+        Never use a path inside a worktree.
+      - Do not commit. For a durable artifact (an approved spec, an ADR, `GLOSSARY.md`), create a task
+        for a worker that can edit files. That worker commits the artifact on the goal branch.
+      - Create tasks in stage order. Do not create the task of the next stage until the gate of the current stage passes.
+        A task that does not exist cannot be claimed.
+      - Do not send a message only to acknowledge. For a note that needs no action now, use `coord msg --fyi`.
+      - Before you revise an artifact that a reviewer read, copy it to `<name>.r<round>.md`. Name both files
+        in the review task. The reviewer reads `diff -u` of the two files and checks the open findings only.
+      #{GRAPH_RULE}
+    TEXT
+
+    # The architect takes goals from the project manager when that role exists,
+    # and takes requests from the user directly when it does not. Two variants so
+    # the generated file never points at a role nobody runs.
+    ARCHITECT_LOOP_PM = <<~LOOP
+      Work loop:
+      1. Read goals from the project manager: `coord inbox architect`. Each goal message names a goal id.
+      #{ARCHITECT_GOAL_STEPS}
+      10. Report back: `coord msg --from architect project-manager "<summary>"`.
+      11. #{ARCHITECT_DECISIONS}
+      12. Use `coord broadcast --from architect "<text>"` for notices to workers.
+          Add `--to all` only for a change that the project manager must know. Use `coord log` to see what happened.
+
+      Available roles:
+      %{roles}
+
+      Rules:
+      #{ARCHITECT_RULES}
+      - Take goals only from the project manager. Never take requests directly from the user.
+      #{STE_RULE}
+      #{SUBAGENT_RULE}
+    LOOP
+
+    ARCHITECT_LOOP_DIRECT = <<~LOOP
+      Work loop:
+      1. Read the user's request from this session. Create a goal for it:
+         `coord goal add --title "<outcome>"`. The command prints the goal id.
+      #{ARCHITECT_GOAL_STEPS}
+      10. Report the outcome to the user in this session.
+      11. #{ARCHITECT_DECISIONS}
+      12. Use `coord broadcast --from architect "<text>"` for notices to workers.
+          Use `coord log` to see what happened.
+
+      Available roles:
+      %{roles}
+
+      Rules:
+      #{ARCHITECT_RULES}
+      - Take requests from the user directly. This project has no project manager.
+      #{STE_RULE}
+      #{SUBAGENT_RULE}
+    LOOP
+
+    # The user can give the project manager a budget (`maf team set`) and let it
+    # run the team. Dispatched workers cost no tokens while idle, so the rules
+    # scale on backlog, not on cost.
+    TEAM_RULES = <<~TEXT.strip
+      - If the user gives you a team budget, record it: `maf team set --max <n> --allow <harness[:model]> ...`.
+        Then manage the team yourself in dispatch mode. `maf prepare ... --dispatch` starts the worker in the background.
+      - Check the team with `maf team`. It shows the budget, each worker, and the tasks by role.
+      - Staff the architect first, with `--dispatch`. A goal needs the architect before any other worker.
+        A dispatched architect starts on each message. An idle interactive architect reads nothing.
+      - Check who runs with `coord who`. A role without a live worker does not read its messages.
+      - If coord reports "No worker runs role <role>", add a worker for that role.
+      - If a role has more than three backlog tasks and the budget has a free slot, add a worker for that role.
+      - If a role has no tasks and no open goal needs it, retire its extra workers.
+        Keep one worker per role that an open goal needs.
+      - If the budget is full, replace an idle worker: `--replace <idle-worker>`.
+      - Report each team change to the user in one line.
+    TEXT
+
+    PM_LOOP = <<~LOOP
+      Work loop:
+      1. Read the user's request. Interview the user, as the duties describe.
+      2. Turn the request into one goal. Create the goal at the start of the interview:
+         `coord goal add --title "<outcome>"`.
+         The command prints the goal id and creates the goal branch. The glossary draft path needs the goal id.
+      3. When the interview ends, hand the goal to the architect:
+           coord msg --from project-manager architect "GOAL <goal-id>: <goal>"
+      4. Check status with `coord goal list` and `coord goal show <goal-id>` when the user asks.
+         %{wait_instruction}
+         Never poll with sleep or with repeated status commands. Each check sends your whole context again.
+      5. Summarize the report for the user.
+      6. #{PM_DECISIONS}
+
+      Rules:
+      - Never edit source files. Never create tasks; only the architect creates tasks.
+      - Change the team when the user asks. Do not ask the user to run setup steps.
+        Add a worker: `maf prepare <harness> <role>_<n>`.
+        Replace a worker: `maf prepare <harness> <role>_<n> --replace <old-role>_<n>`.
+        Remove a worker: `maf retire <role>_<n>`.
+        Give the user the two commands that `maf prepare` prints: `cd <worktree>` and `maf start`.
+        If `maf` reports that the old worker still runs, ask the user to stop that session. Then run the command again.
+      #{TEAM_RULES}
+      - Send goals to the architect only. Never dispatch work to other roles directly.
+      - Send the user's decisions to the architect in one message, not one message per decision.
+        Each message starts an architect run. For a note that needs no action now, use `coord msg --fyi`.
+      - Do not read the project docs in full. Each file that you read stays in your context for the whole session.
+        Ask the architect, or start one subagent that returns a summary of at most 300 words.
+      - If no report has arrived yet, tell the user and check again with `coord inbox project-manager`.
+      #{STE_RULE}
+      #{SUBAGENT_RULE}
+    LOOP
+  end
+end

data/lib/maf/flow/report.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # Report prints the result of a run and the next steps for the user.
+    class Report
+      def initialize(project, roles, hermes_pending)
+        @project = project
+        @roles = roles
+        @hermes_pending = hermes_pending
+      end
+
+      def print(results)
+        puts "", "Generated role files:", results.map { |result| generated_line(result) }
+        %i[print_missing_models print_unknown_models print_unembeddable print_sessions]
+          .each { |name| send(name, results) }
+        print_hermes_reminder
+      end
+
+      private
+
+      # The hook steps print at install time, far above the last lines the user
+      # reads. Repeat the state here so the flow is not started with a dead hook.
+      def print_hermes_reminder
+        return unless @hermes_pending
+
+        puts "The Hermes hook is not active yet. Finish the steps above.",
+             "Then run `maf update` to confirm the hook is ready."
+      end
+
+      def generated_line(result)
+        "  #{result[:status].to_s.ljust(7)} #{result[:agent][:harness]}:" \
+          "#{result[:agent][:role]} -> #{result[:dest]}"
+      end
+
+      def print_missing_models(results)
+        missing = results.reject { |result| result[:model] }.map { |result| "  #{model_hint(result)}" }
+        return if missing.empty?
+
+        puts "", "No model chosen for these roles. maf leaves the choice to you. Suggestions:", missing,
+             "  Set one with: --model <role>=<provider/model>"
+      end
+
+      # A dispatched run with an unknown model fails before it reaches the model.
+      def print_unknown_models(results)
+        unknown = results.select { |r| r[:model] && !Models.known?(r[:agent][:harness], r[:model]) }
+        return if unknown.empty?
+
+        puts "", "WARNING: the harness does not list these models. Check the name for a typo:",
+             unknown.map { |r| "  #{r[:agent][:harness]}:#{r[:agent][:role]} -> #{r[:model]}" },
+             "  Fix one with: maf add HARNESS:ROLE:MODEL"
+      end
+
+      def model_hint(result)
+        role = result[:agent][:role]
+        "#{role}: #{@roles.fetch(role).fetch("model_hint")}"
+      end
+
+      PASTE_HINT = %(  "Run coord inbox <role>. Then work the pending tasks assigned to you. Repeat.")
+
+      def print_sessions(results)
+        puts "", "Next: start one session per agent in #{@project}:",
+             results.map { |result| "  maf start #{result[:agent][:harness]} #{result[:agent][:role]}" },
+             "", "In each worker session, paste:",
+             PASTE_HINT, entry_point_hint(results)
+      end
+
+      def entry_point_hint(results)
+        return "In the architect session, describe what you want built." if results.none? { |r| pm?(r) }
+
+        "Talk to the project manager session. It hands goals to the architect."
+      end
+
+      def pm?(result) = result[:agent][:role] == "project-manager"
+
+      def print_unembeddable(results)
+        list = results.select { |r| r[:model] && %w[codex hermes].include?(r[:agent][:harness]) }
+        return if list.empty?
+
+        puts "", "These harnesses cannot embed a model in the role file. Set it in the harness:",
+             list.map { |r| "  #{r[:agent][:harness]}:#{r[:agent][:role]} -> #{model_command(r)}" }
+      end
+
+      def model_command(result)
+        result[:agent][:harness] == "codex" ? "codex -m #{result[:model]}" : "hermes model"
+      end
+    end
+  end
+end

data/lib/maf/flow/role_catalog.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # RoleCatalog merges the built-in roles with the project roles. A project
+    # role in .maf/roles.yml adds a role or replaces a built-in role.
+    class RoleCatalog
+      FILE = ".maf/roles.yml"
+      DEFAULTS = { "model_hint" => "", "can_edit" => true }.freeze
+
+      def initialize(project)
+        @project = project
+      end
+
+      def roles
+        @roles ||= builtin.merge(custom.transform_values { |data| DEFAULTS.merge(data) })
+      end
+
+      def source(name)
+        return "project" if custom.key?(name)
+
+        "built-in"
+      end
+
+      def custom
+        @custom ||= File.exist?(path) ? load_file(path) : {}
+      end
+
+      def path = File.join(@project, FILE)
+
+      private
+
+      def builtin = load_file(File.join(TEMPLATES, "roles.yml"))
+
+      def load_file(file)
+        YAML.safe_load_file(file).fetch("roles", nil) || {}
+      end
+    end
+  end
+end

data/lib/maf/flow/role_files.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # RoleFiles renders and writes the role file of each agent.
+    class RoleFiles
+      MARKER = ">>> multi-agent-flow >>>"
+
+      def initialize(options, roles)
+        @options = options
+        @roles = roles
+        @prompts = PromptBuilder.new(roles, options.agents, Workflow.new(options.project).block)
+      end
+
+      def generate
+        @options.agents.map { |agent| generate_agent(agent) }
+      end
+
+      private
+
+      def generate_agent(agent)
+        role = agent[:role]
+        model = @options.model_for(agent)
+        dest = destination(agent[:harness], role)
+        content = render(agent[:harness], role, @roles.fetch(role), model)
+        { agent: agent, dest: dest, status: write(dest, content), model: model }
+      end
+
+      # Hermes skills live in a global ~/.hermes/skills/ directory, not the
+      # project. Namespace by project so two projects using the same role
+      # don't overwrite each other's skill.
+      def destination(harness, role)
+        return hermes_path(role) if harness == "hermes"
+
+        File.join(@options.project, Flow.role_path(harness, role)) if %w[opencode claude codex].include?(harness)
+      end
+
+      def hermes_path(role)
+        File.join(@options.hermes_dir, "#{File.basename(@options.project)}-#{role}", "SKILL.md")
+      end
+
+      def render(harness, role, data, model)
+        template = File.read(File.join(TEMPLATES, "#{harness}.md.erb"))
+        values = { prompt: @prompts.build(harness, role, data), model: model }
+        ERB.new(template, trim_mode: "-").result_with_hash(**template_values(role, data), **values)
+      end
+
+      def template_values(role, data)
+        { role: role, title: data.fetch("title"), description: data.fetch("description"),
+          can_edit: data.fetch("can_edit"), project: File.expand_path(@options.project) }
+      end
+
+      def write(dest, content)
+        existed = File.exist?(dest)
+        return :skip if existed && File.read(dest) == content
+        return :refuse if existed && refuse?(dest)
+
+        @options.check? ? :check : save(dest, content, existed)
+      end
+
+      def save(dest, content, existed)
+        FileUtils.mkdir_p(File.dirname(dest))
+        File.write(dest, content)
+        existed ? :update : :create
+      end
+
+      def refuse?(dest)
+        !File.read(dest).include?(MARKER) && !@options.force?
+      end
+    end
+  end
+end

data/lib/maf/flow/role_stub.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # RoleStub adds a stub role to .maf/roles.yml. The stub holds the four duty
+    # parts. A role that exists already stays as it is.
+    class RoleStub
+      TEMPLATE = File.join(TEMPLATES, "role-stub.yml.erb")
+
+      def initialize(project, name)
+        @catalog = RoleCatalog.new(project)
+        @name = name
+      end
+
+      # Returns :create or :skip.
+      def add
+        abort "flow: invalid role name '#{@name}' (use a-z, 0-9, hyphen)" unless @name.match?(/\A[a-z][a-z0-9-]*\z/)
+        return :skip if @catalog.custom.key?(@name)
+
+        write
+        :create
+      end
+
+      private
+
+      def write
+        FileUtils.mkdir_p(File.dirname(@catalog.path))
+        File.write(@catalog.path, existing + entry)
+      end
+
+      def existing
+        @catalog.custom.empty? ? "roles:\n" : File.read(@catalog.path).sub(/\n*\z/, "\n\n")
+      end
+
+      def entry = ERB.new(File.read(TEMPLATE), trim_mode: "-").result_with_hash(name: @name)
+    end
+  end
+end

data/lib/maf/flow/roster.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # Roster merges the agents saved in .maf/config.json with the --agent and
+    # --remove specs of this run. A saved model ranks below --model.
+    class Roster
+      def initialize(project)
+        path = File.join(project, ".maf/config.json")
+        @saved = File.exist?(path) ? JSON.parse(File.read(path)).fetch("agents", []) : []
+      end
+
+      def merge(added, removed)
+        kept = saved.map { |a| added.find { |b| same?(a, b) }&.merge(saved_model: a[:saved_model]) || a }
+        agents = kept + added.reject { |b| kept.any? { |a| same?(a, b) } }
+        agents.reject { |a| removed.any? { |b| same?(a, b) } }
+      end
+
+      private
+
+      def saved
+        @saved.map { |a| { harness: a["harness"], role: a["role"], saved_model: a["model"] } }
+      end
+
+      def same?(one, other) = one[:harness] == other[:harness] && one[:role] == other[:role]
+    end
+  end
+end

data/lib/maf/flow/validator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # Validator checks the project, the harnesses, and the roles of one run.
+    class Validator
+      def self.project!(options)
+        project = options.project
+        abort "flow: --project is required" if project.nil?
+        abort "flow: project is not a directory: #{project}" unless Dir.exist?(project)
+
+        options.project = File.realpath(project)
+      end
+
+      def initialize(options, roles)
+        @options = options
+        @roles = roles
+      end
+
+      # A removal may leave no agents. Only a run that removes nothing needs one.
+      def run
+        @options.agents = Roster.new(@options.project).merge(@options.agents, @options.removed)
+        abort "flow: no agents. Add one with --agent HARNESS:ROLE" if @options.agents.empty? && @options.removed.empty?
+
+        @options.agents.each { |agent| check(agent) }
+      end
+
+      private
+
+      def check(agent)
+        abort "flow: unknown harness '#{agent[:harness]}' (use #{HARNESSES.join(", ")})" unless known?(agent)
+        abort "flow: unknown role '#{agent[:role]}'" unless @roles.key?(agent[:role])
+      end
+
+      def known?(agent) = HARNESSES.include?(agent[:harness])
+    end
+  end
+end

data/lib/maf/flow/workflow.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # Workflow reads the stage instructions of a project from .maf/workflow.md.
+    # Only the orchestrator prompt receives the text.
+    class Workflow
+      FILE = ".maf/workflow.md"
+      HEADING = "Workflow:"
+
+      def initialize(project)
+        @path = File.join(project, FILE)
+      end
+
+      # The prompt block, or nil if the project has no workflow.
+      def block
+        return nil unless File.exist?(@path)
+
+        text = File.read(@path).strip
+        text.empty? ? nil : "#{HEADING}\n#{indent(text)}"
+      end
+
+      private
+
+      def indent(text) = text.lines.map { |line| line.strip.empty? ? line : "  #{line}" }.join
+    end
+  end
+end