maf 0.1.0

data/lib/maf/flow/hermes_hook.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # HermesHook reports the state of the hook that picks up tasks when a Hermes
+    # session ends. Hermes keeps hooks in the global config.yaml and asks for a
+    # one-time consent, so the flow prints commands instead of editing the file.
+    # Every method takes a path, so a test can use fixtures.
+    module HermesHook
+      EVENT = "on_session_end"
+      SCRIPT_NAME = "next-task.sh"
+      TIMEOUT = 30
+      # Hermes rounds the recorded approval time to microseconds, so compare with
+      # a small tolerance. A rewritten hook moves the mtime far past it.
+      MTIME_TOLERANCE = 2
+
+      def self.declared?(config_yaml, script_path)
+        return false unless File.exist?(config_yaml)
+
+        content = File.read(config_yaml)
+        content.include?(script_path) || content.include?(SCRIPT_NAME)
+      end
+
+      def self.approved?(allowlist, script_path, mtime)
+        entry = approvals(allowlist).find { |item| item["command"] == script_path && item["event"] == EVENT }
+        entry ? (mtime - Time.iso8601(entry["script_mtime_at_approval"].to_s)).abs <= MTIME_TOLERANCE : false
+      rescue ArgumentError, TypeError
+        false
+      end
+
+      def self.approvals(allowlist)
+        return [] unless File.exist?(allowlist)
+
+        JSON.parse(File.read(allowlist)).fetch("approvals", [])
+      rescue JSON::ParserError
+        []
+      end
+
+      def self.config_command(script_path)
+        %(hermes config set hooks.#{EVENT} '[{"command":"#{script_path}","timeout":#{TIMEOUT}}]')
+      end
+
+      def self.approve_command = "hermes chat --oneshot --accept-hooks -q ok"
+
+      def self.check_command = "hermes hooks doctor"
+    end
+  end
+end

data/lib/maf/flow/hermes_hook_setup.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # HermesHookSetup installs the Hermes hook script. It prints the steps that
+    # the user must do. The flow never edits the Hermes config: the file is
+    # comment-rich, and Hermes guards it as security-sensitive. It prints only
+    # the step that is still missing.
+    class HermesHookSetup
+      def initialize
+        @home = File.join(Dir.home, ".hermes")
+        @script = File.join(@home, "agent-hooks", HermesHook::SCRIPT_NAME)
+      end
+
+      # Returns true when the user has steps left.
+      def install
+        install_files
+        steps = self.steps(File.mtime(@script))
+        return puts("  hook ready:   #{@script}") || false if steps.empty?
+
+        print_steps(steps) || true
+      end
+
+      private
+
+      def install_files
+        HookFiles.copy(File.join(ASSETS, "harness-hooks", "session-guard.rb"),
+                       File.join(File.dirname(@script), "session-guard.rb"))
+        HookFiles.copy(File.join(ASSETS, "harness-hooks", "next-task-hermes.sh"), @script)
+      end
+
+      def print_steps(steps)
+        puts "", "  Hermes hook: #{@script}", "  The hook does not run yet. Do these steps one time.", ""
+        steps.each_with_index { |step, index| puts format_step(step, index) }
+        nil
+      end
+
+      def format_step(step, index)
+        lines = ["    #{index + 1}. #{step[:title]}", "         #{step[:command]}"]
+        lines << "         #{step[:note]}" if step[:note]
+        "#{lines.join("\n")}\n"
+      end
+
+      def steps(mtime)
+        steps = [declare_step, approve_step(mtime)].reject { |step| step[:done] }
+        steps << check_step unless steps.empty?
+        steps
+      end
+
+      def declare_step
+        { done: HermesHook.declared?(File.join(@home, "config.yaml"), @script),
+          title: "Declare the hook in the Hermes config:",
+          command: HermesHook.config_command(@script),
+          note: "Keep your other on_session_end entries. Add this entry to that list." }
+      end
+
+      def approve_step(mtime)
+        { done: HermesHook.approved?(File.join(@home, "shell-hooks-allowlist.json"), @script, mtime),
+          title: "Approve the hook one time:",
+          command: HermesHook.approve_command,
+          note: "Hermes stores the consent for this version of the script." }
+      end
+
+      def check_step
+        { done: false, title: "Check the hook:", command: HermesHook.check_command, note: nil }
+      end
+    end
+  end
+end

data/lib/maf/flow/hook_files.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # HookFiles copies a hook script from the assets and makes it executable.
+    module HookFiles
+      def self.copy(src, dest)
+        FileUtils.mkdir_p(File.dirname(dest))
+        return if File.exist?(dest) && File.read(dest) == File.read(src)
+
+        FileUtils.install(src, dest, mode: 0o755)
+        puts "  hook install: #{dest}"
+      end
+    end
+  end
+end

data/lib/maf/flow/hook_installer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # HookInstaller installs the harness hooks that pick up tasks when a
+    # session ends. Claude Code and opencode get theirs from bootstrap.
+    class HookInstaller
+      def initialize(agents, project)
+        @harnesses = agents.map { |a| a[:harness] }.uniq
+        @project = project
+      end
+
+      # Returns true when the Hermes hook needs steps from the user.
+      def install
+        install_codex if @harnesses.include?("codex")
+        @harnesses.include?("hermes") && HermesHookSetup.new.install
+      end
+
+      private
+
+      def install_codex
+        %w[next-task.rb session-guard.rb].each { |name| copy_hook(name) }
+        CodexHooks.new(@project).install
+        LegacyCodexHook.new.remove
+      end
+
+      def copy_hook(name)
+        HookFiles.copy(File.join(ASSETS, "harness-hooks", name),
+                       File.join(@project, ".maf", "coordination", "harness-hooks", name))
+      end
+    end
+  end
+end

data/lib/maf/flow/legacy_codex_hook.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Maf
+  module Flow
+    # Remove only the global hook that MAF installed.
+    class LegacyCodexHook
+      DISABLED = <<~RUBY
+        #!/usr/bin/env ruby
+        # next-task.rb - Stop hook for Claude Code and Codex.
+        # The legacy global MAF hook is disabled. Use project hooks with maf start.
+        exit 0
+      RUBY
+
+      def initialize(home = Dir.home)
+        @script = File.join(home, ".codex", "hooks", "next-task.rb")
+        @path = File.join(home, ".codex", "hooks.json")
+      end
+
+      def remove
+        return unless owned?
+
+        disable
+        clean_config if File.exist?(@path)
+      end
+
+      def clean_config
+        clean(JSON.parse(File.read(@path)))
+      rescue JSON::ParserError
+        warn "flow: invalid JSON in #{@path}; the legacy hook is disabled but its registration remains"
+      end
+
+      private
+
+      def disable
+        File.write(@script, DISABLED) unless File.read(@script) == DISABLED
+      end
+
+      def owned?
+        File.file?(@script) && File.read(@script).include?("next-task.rb - Stop hook for Claude Code and Codex.")
+      end
+
+      def clean(data)
+        updated = stripped(data)
+        return if updated == data
+
+        File.write(@path, JSON.pretty_generate(updated))
+        puts "  hook remove:  #{@path} (legacy global MAF hook)"
+      end
+
+      def stripped(data)
+        hooks = data.fetch("hooks", {}).transform_values { |entries| strip_entries(entries) }.reject { |_, v| v.empty? }
+        hooks.empty? ? data.except("hooks") : data.merge("hooks" => hooks)
+      end
+
+      def strip_entries(entries)
+        entries.map { |entry| entry.merge("hooks" => entry.fetch("hooks", []).reject { |hook| ours?(hook) }) }
+          .reject { |entry| entry["hooks"].empty? }
+      end
+
+      def ours?(hook)
+        command = Shellwords.split(hook["command"].to_s)
+        command.size == 2 && File.basename(command.first) == "ruby" &&
+          [@script, "~/.codex/hooks/next-task.rb"].include?(command.last)
+      rescue ArgumentError
+        false
+      end
+    end
+  end
+end

data/lib/maf/flow/manifest.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # Manifest writes .maf/config.json, the record of the agents of a project.
+    class Manifest
+      def initialize(options, roles)
+        @options = options
+        @roles = roles
+      end
+
+      def write
+        return if @options.check?
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, JSON.pretty_generate(data))
+      end
+
+      private
+
+      def path
+        File.join(@options.project, ".maf/config.json")
+      end
+
+      def data
+        data = kept_keys.merge("generated_at" => Time.now.utc.iso8601, "agents" => @options.agents.map { |a| entry(a) })
+        # Only record hermes_dir when it differs from the default: the default is
+        # an absolute home path that would leak into a committed manifest.
+        data["hermes_dir"] = @options.hermes_dir unless @options.hermes_dir == DEFAULT_HERMES_DIR
+        data
+      end
+
+      # can_edit lets maf start, the dispatcher, and the git commit guard limit
+      # a role without the role definitions.
+      def entry(agent)
+        { harness: agent[:harness], role: agent[:role], model: @options.model_for(agent),
+          can_edit: @roles.fetch(agent[:role]).fetch("can_edit") }
+      end
+
+      # Other tools own other keys (maf team: "team"; users: "base_branch").
+      # A re-run must keep them.
+      def kept_keys
+        return {} unless File.exist?(path)
+
+        JSON.parse(File.read(path)).except("generated_at", "agents", "hermes_dir")
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/lib/maf/flow/mcp_config.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # McpConfig writes the graphify MCP server into a config file of the flow,
+    # in .maf/mcp/. The project's .mcp.json and opencode.json stay as they are.
+    # `maf start` and the dispatcher pass the file: Claude Code reads it with
+    # --mcp-config, opencode with the OPENCODE_CONFIG variable.
+    # The server runs `vault mcp`. A foreign entry with the same name stays.
+    # Codex and Hermes keep MCP servers in a global user file. maf does not
+    # edit that file. It prints the command that adds the server instead.
+    class McpConfig
+      NAME = "graphify"
+      ARGS = %w[ruby .maf/bin/vault mcp].freeze
+      SCHEMA = "https://opencode.ai/config.json"
+      TARGETS = {
+        "claude" => { file: ".maf/mcp/claude.json", key: "mcpServers",
+                      entry: { "command" => ARGS.first, "args" => ARGS.drop(1) } },
+        "opencode" => { file: ".maf/mcp/opencode.json", key: "mcp",
+                        entry: { "type" => "local", "command" => ARGS, "enabled" => true } }
+      }.freeze
+
+      def self.targets = TARGETS
+
+      GLOBAL_COMMANDS = { "codex" => "codex mcp add %<name>s -- ruby %<vault>s mcp",
+                          "hermes" => "hermes mcp add %<name>s --command ruby --args %<vault>s mcp" }.freeze
+
+      # The shell command for a harness with a global MCP config, or nil.
+      def self.global_command(harness, project)
+        vault = File.join(project, ".maf", "bin", "vault")
+        GLOBAL_COMMANDS[harness]&.then { |text| format(text, name: "#{NAME}-#{File.basename(project)}", vault: vault) }
+      end
+
+      def initialize(project, harness)
+        @target = TARGETS.fetch(harness)
+        @path = File.join(project, @target[:file])
+      end
+
+      # Returns :create, :skip, or :refuse.
+      def write
+        data = load
+        return :refuse unless data
+
+        section = data.fetch(@target[:key], {})
+        section.key?(NAME) ? compare(section[NAME]) : add(data, section)
+      end
+
+      private
+
+      def compare(entry) = entry == @target[:entry] ? :skip : :refuse
+
+      def add(data, section)
+        save(data.merge(@target[:key] => section.merge(NAME => @target[:entry])))
+        :create
+      end
+
+      # An unreadable file gives nil. maf never overwrites a file it cannot read.
+      def load
+        data = File.exist?(@path) ? JSON.parse(File.read(@path)) : {}
+        data.is_a?(Hash) ? data : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      def save(data)
+        data = { "$schema" => SCHEMA }.merge(data) if @target[:key] == "mcp" && !data.key?("$schema")
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, "#{JSON.pretty_generate(data)}\n")
+      end
+    end
+  end
+end

data/lib/maf/flow/mcp_installer.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # McpInstaller adds the graphify MCP server for each harness of the run.
+    # The key "mcp": false in .maf/config.json turns it off.
+    class McpInstaller
+      def initialize(options)
+        @options = options
+        @project = options.project
+      end
+
+      def install
+        return if @options.check? || disabled?
+
+        @options.agents.map { |a| a[:harness] }.uniq.each { |harness| install_for(harness) }
+      end
+
+      private
+
+      def install_for(harness)
+        if McpConfig.targets.key?(harness)
+          report(harness, McpConfig.new(@project, harness).write)
+        elsif (command = McpConfig.global_command(harness, @project))
+          puts "mcp: the #{harness} harness keeps MCP servers in a global file. Add the server yourself:\n  #{command}"
+        end
+      end
+
+      def report(harness, status)
+        file = McpConfig.targets.fetch(harness).fetch(:file)
+        return puts("mcp: wrote the graphify server to #{file}") if status == :create
+        return unless status == :refuse
+
+        warn "mcp: #{file} has another graphify entry, or it is not valid JSON. maf left the file as it is."
+      end
+
+      def disabled?
+        path = File.join(@project, ".maf", "config.json")
+        File.exist?(path) && JSON.parse(File.read(path))["mcp"] == false
+      rescue JSON::ParserError
+        false
+      end
+    end
+  end
+end

data/lib/maf/flow/models.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Maf
+  module Flow
+    # Models finds the installed harnesses and the models that each one offers.
+    # maf add shows them as choices and warns about a model name that the
+    # harness does not know: a typo makes every dispatched run fail.
+    # A list is nil when maf cannot read it. Then every name counts as known.
+    module Models
+      # Claude Code has no command that lists models. The aliases follow the
+      # newest model of each family. A full ID is claude-<family>-<version>.
+      CLAUDE = %w[claude-opus-5-5 claude-sonnet-5-5 claude-haiku-5-5 claude-fable-5-1 opus sonnet haiku fable].freeze
+      CLAUDE_NAME = /\A(?:(?:opus|sonnet|haiku|fable)(?:\[1m\])?|opusplan|default|best|
+                       (?:[\w.-]+\.)?(?:anthropic\.)?claude-(?:opus|sonnet|haiku|fable)-\d[\w.:@\[\]-]*)\z/x
+      CODEX_CACHE = File.join(Dir.home, ".codex", "models_cache.json")
+
+      # Without any harness on PATH, maf shows all of them: the user may install one later.
+      def self.installed
+        found = HARNESSES.select { |harness| on_path?(harness) }
+        found.empty? ? HARNESSES : found
+      end
+
+      def self.on_path?(command)
+        ENV["PATH"].to_s.split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, command)) }
+      end
+
+      def self.for(harness)
+        @lists ||= {}
+        return @lists[harness] if @lists.key?(harness)
+
+        @lists[harness] = { "claude" => -> { CLAUDE }, "codex" => -> { codex }, "opencode" => -> { opencode } }
+                          .fetch(harness, -> {}).call
+      end
+
+      def self.known?(harness, model)
+        return model.match?(CLAUDE_NAME) if harness == "claude"
+
+        self.for(harness).nil? || self.for(harness).include?(model)
+      end
+
+      # Codex keeps the model list of the account in a cache file. Hidden models are internal.
+      def self.codex
+        models = JSON.parse(File.read(CODEX_CACHE)).fetch("models")
+        models.select { |m| m["visibility"] == "list" }.map { |m| m["slug"] }
+      rescue SystemCallError, JSON::ParserError, KeyError, NoMethodError
+        nil
+      end
+
+      def self.opencode
+        return nil unless on_path?("opencode")
+
+        out, status = Open3.capture2("opencode", "models", err: File::NULL)
+        status.success? && !out.strip.empty? ? out.split : nil
+      rescue SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/maf/flow/options.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # Options parses the command line and holds the settings of one run.
+    class Options
+      attr_accessor :project, :agents
+      attr_reader :removed, :models, :hermes_dir, :list_roles
+
+      # Each flag: the OptionParser arguments, and a block that runs in the
+      # Options instance with the flag value.
+      FLAGS = [
+        [["--project DIR"], ->(v) { @project = v }],
+        [["--agent SPEC", "HARNESS:ROLE[:MODEL]"], ->(v) { @agents << parse_agent(v) }],
+        [["--remove SPEC", "HARNESS:ROLE"], ->(v) { @removed << parse_agent(v) }],
+        [["--model PAIR", "ROLE=MODEL"], ->(v) { @models.store(*v.split("=", 2)) }],
+        [["--hermes-dir DIR"], ->(v) { @hermes_dir = File.expand_path(v) }],
+        [["--check"], ->(_) { @check = true }],
+        [["--force"], ->(_) { @force = true }],
+        [["--no-bootstrap"], ->(_) { @bootstrap = false }],
+        [["--list-roles"], ->(_) { @list_roles = true }]
+      ].freeze
+
+      def initialize(argv)
+        @argv, @agents, @removed, @models = argv, [], [], {}
+        @hermes_dir = DEFAULT_HERMES_DIR
+        @check = @force = @list_roles = false
+        @bootstrap = true
+      end
+
+      def check? = @check
+      def force? = @force
+      def bootstrap? = @bootstrap
+
+      def parse
+        parser.parse!(@argv)
+        self
+      end
+
+      # Flags that take a value. maf uses them to tell flag values from agent specs.
+      def value_flags
+        parser.top.list.grep(OptionParser::Switch::RequiredArgument).flat_map(&:long)
+      end
+
+      def model_for(agent)
+        agent[:model] || @models[agent[:role]] || agent[:saved_model] || DEFAULT_MODELS[agent[:harness]]
+      end
+
+      private
+
+      def parser
+        OptionParser.new do |o|
+          o.banner = "Usage: maf add|remove|update [HARNESS:ROLE ...] [options]"
+          FLAGS.each { |args, set| o.on(*args) { |value| instance_exec(value, &set) } }
+          o.on("-h", "--help") { puts o; exit 0 }
+        end
+      end
+
+      def parse_agent(spec)
+        harness, role, model = spec.split(":", 3)
+        { harness: harness, role: role, model: model }
+      end
+    end
+  end
+end

data/lib/maf/flow/prompt_builder.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # PromptBuilder builds the prompt text of one role file.
+    class PromptBuilder
+      def initialize(roles, agents, workflow = nil)
+        @roles = roles
+        @agents = agents
+        @workflow = workflow
+      end
+
+      def build(harness, role, data) = "#{role_prompt(harness, role, data).rstrip}\n\n#{CONTRACT}\n"
+
+      private
+
+      def role_prompt(harness, role, data)
+        return project_manager_prompt(harness, data) if role == "project-manager"
+        return architect_prompt(harness, data) if role == "architect"
+
+        worker_prompt(harness, role, data)
+      end
+
+      def worker_prompt(harness, role, data)
+        loop_text = format(WORKER_LOOP, role: role, no_task_instruction: no_task_line(harness))
+        "#{intro(data)}\n\n#{duties_block(data)}\n\n#{loop_text}"
+      end
+
+      # Claude Code wakes an idle session with the board-watch hook, and opencode
+      # with the board-watch plugin. So these agents stop instead of waiting:
+      # each return of a wait costs one model call over the whole context.
+      # Codex waits in its stop hook after `coord await`. Hermes cannot be
+      # woken, so it blocks in `coord next --wait`.
+      # The dispatcher adds the report block rule to each dispatched prompt.
+      def no_task_line(harness)
+        return NO_TASK_AWAIT if harness == "codex"
+
+        WAKE_HARNESSES.include?(harness) ? NO_TASK_STOP : NO_TASK_WAIT
+      end
+
+      def architect_prompt(harness, data)
+        loop_text = project_manager? ? ARCHITECT_LOOP_PM : ARCHITECT_LOOP_DIRECT
+        "#{intro(data)} You do not implement code yourself.\n\n#{duties_block(data)}\n\n" \
+          "#{format(loop_text, roles: dispatch_roles_text)}#{claude_rule(harness)}#{workflow_block}"
+      end
+
+      # The loop text ends with a newline, so the rule lands as the last rule line.
+      def claude_rule(harness) = harness == "claude" ? "#{CLAUDE_ARCHITECT_RULE}\n" : ""
+
+      # The workflow goes into the orchestrator prompt only. Workers stay workflow-blind.
+      def workflow_block = @workflow ? "\n\n#{@workflow}" : ""
+
+      def project_manager?
+        @agents.any? { |a| a[:role] == "project-manager" }
+      end
+
+      def project_manager_prompt(harness, data)
+        "#{intro(data)} You do not plan tasks or implement code yourself.\n\n" \
+          "#{duties_block(data)}\n\n#{format(PM_LOOP, wait_instruction: PM_WAIT.fetch(harness, PM_WAIT_DEFAULT))}"
+      end
+
+      def intro(data)
+        "You are the #{data.fetch("title")} for this project."
+      end
+
+      def duties_block(data)
+        lines = data.fetch("duties").strip.lines.map { |line| line.strip.empty? ? line : "  #{line}" }
+        "Duties:\n#{lines.join}"
+      end
+
+      # What the architect can dispatch to: this run's worker roles, not every
+      # role in roles.yml. Advertising a role nobody generated a session for
+      # means tasks pile up unclaimed forever.
+      def dispatch_roles
+        @agents.map { |a| a[:role] }.uniq - DISPATCH_EXCLUDE
+      end
+
+      def dispatch_roles_text
+        return "  (none requested yet in this run)" if dispatch_roles.empty?
+
+        dispatch_roles.map { |r| "  - #{r}: #{@roles.fetch(r).fetch("description")}" }.join("\n")
+      end
+    end
+  end
+end