maf 0.1.0

data/lib/maf/flow.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# flow.rb - generate harness-specific role files for the multi-agent flow.
+#
+# maf add, maf remove, maf update, and maf roles run Flow::Generator.
+# Options: --project DIR [--agent HARNESS:ROLE ...] [--remove HARNESS:ROLE ...]
+#          [--model ROLE=MODEL] [--hermes-dir DIR] [--check] [--force] [--no-bootstrap]
+#          [--list-roles]
+#
+# HARNESS is one of: opencode, claude, codex, hermes.
+# A re-run keeps the agents in .maf/config.json. --agent adds an agent.
+# --remove drops an agent. Without --agent, a re-run regenerates the current agents.
+# Idempotent: identical files are skipped, changed files are updated, and
+# foreign files are refused unless --force is given.
+require "fileutils"
+require "yaml"
+require "erb"
+require "json"
+require "optparse"
+require "rbconfig"
+require "time"
+require_relative "shared/roles"
+
+abort "flow: Ruby 3.0+ required (current: #{RUBY_VERSION})." if RUBY_VERSION.split(".").first.to_i < 3
+
+module Maf
+  module Flow
+    ROOT = File.expand_path("../..", __dir__)
+    TEMPLATES = File.join(ROOT, "templates")
+    ASSETS = File.join(ROOT, "assets")
+    HARNESSES = %w[opencode claude codex hermes].freeze
+    DEFAULT_HERMES_DIR = File.join(Dir.home, ".hermes", "skills")
+
+    # Model a harness gets when neither --agent nor --model names one.
+    # Other harnesses have no safe default, so their CLI picks the model.
+    DEFAULT_MODELS = { "claude" => "claude-opus-5-5" }.freeze
+
+    # Roles that dispatch or coordinate instead of implementing. They are never
+    # advertised as dispatch targets in the architect prompt.
+    LEADS = Maf::Shared::Roles::LEADS
+    DISPATCH_EXCLUDE = LEADS
+
+    READ_ONLY_TOOLSETS = Maf::Shared::Roles::READ_ONLY_TOOLSETS
+
+    MAF_DIR = ".maf"
+
+    # The folder where a harness looks for role files. It is a symlink into
+    # .maf/agents/<harness>/, where the flow keeps the role files.
+    HARNESS_DIRS = { "opencode" => ".opencode/agents", "claude" => ".claude/agents",
+                     "codex" => ".codex/prompts" }.freeze
+
+    # The role file path inside the project. Hermes keeps role files outside
+    # the project, so it has no path here.
+    def self.role_path(harness, role)
+      HARNESS_DIRS.key?(harness) ? File.join(MAF_DIR, "agents", harness, "#{role}.md") : nil
+    end
+  end
+end
+
+require_relative "local_exclude"
+require_relative "flow/prompt_text"
+require_relative "flow/hermes_hook"
+require_relative "flow/roster"
+require_relative "flow/role_catalog"
+require_relative "flow/role_stub"
+require_relative "flow/workflow"
+require_relative "flow/options"
+require_relative "flow/prompt_builder"
+require_relative "flow/hook_files"
+require_relative "flow/hermes_hook_setup"
+require_relative "flow/codex_hooks"
+require_relative "flow/legacy_codex_hook"
+require_relative "flow/hook_installer"
+require_relative "flow/agent_links"
+require_relative "flow/mcp_config"
+require_relative "flow/mcp_installer"
+require_relative "flow/role_files"
+require_relative "flow/manifest"
+require_relative "flow/models"
+require_relative "flow/report"
+require_relative "flow/validator"
+require_relative "flow/harness_linker"
+require_relative "flow/bootstrapper"
+require_relative "flow/generator"

data/lib/maf/local_exclude.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "shared/git_exclude"
+
+module Maf
+  # LocalExclude keeps the paths of the flow in the .git/info/exclude file of
+  # the clone. The flow is a tool, not a part of the project, so nothing that
+  # runs it goes into git. info/exclude is local to the clone, and every
+  # worktree of the repository shares it. The paths sit in one marked block.
+  module LocalExclude
+    BEGIN_LINE = "# >>> multi-agent-flow >>>"
+    END_LINE = "# <<< multi-agent-flow <<<"
+
+    # Adds each path that the block does not list yet.
+    def self.add(dir, *paths)
+      file = exclude_path(dir)
+      file && write(file, (listed(file) + paths).uniq)
+    end
+
+    def self.replace(dir, paths)
+      file = exclude_path(dir)
+      file && write(file, paths)
+    end
+
+    def self.remove(dir)
+      file = exclude_path(dir)
+      File.write(file, outside(File.read(file))) if file && File.exist?(file)
+    end
+
+    def self.listed(file)
+      lines = File.exist?(file) ? File.read(file).lines.map(&:chomp) : []
+      first = lines.index(BEGIN_LINE)
+      last = lines.index(END_LINE)
+      first && last ? lines[(first + 1)...last] : []
+    end
+
+    def self.write(file, paths)
+      FileUtils.mkdir_p(File.dirname(file))
+      text = File.exist?(file) ? outside(File.read(file)) : ""
+      File.write(file, "#{text.chomp}#{"\n" unless text.strip.empty?}#{[BEGIN_LINE, *paths, END_LINE].join("\n")}\n")
+    end
+
+    def self.outside(text)
+      lines = text.lines
+      first = lines.index { |line| line.chomp == BEGIN_LINE }
+      last = lines.index { |line| line.chomp == END_LINE }
+      first && last ? (lines[0...first] + lines[(last + 1)..]).join : text
+    end
+
+    def self.exclude_path(dir) = Maf::Shared::GitExclude.path(dir)
+  end
+end

data/lib/maf/menu.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "prompt"
+
+module Maf
+  # Menu is the interactive mode of maf. It runs the same steps as the
+  # subcommands, but asks for each value.
+  class Menu
+    ACTIONS = { "1" => ["Add agents", :add], "2" => ["Remove an agent", :remove],
+                "3" => ["Start an agent", :start], "4" => ["List roles", :roles],
+                "5" => ["Update the agent files", :update], "6" => ["Uninstall", :uninstall] }.freeze
+
+    def initialize(prompt = Prompt.new)
+      @prompt = prompt
+    end
+
+    def run
+      loop do
+        show_menu
+        break unless handle(@prompt.ask("Choose:"))
+      end
+    end
+
+    # Only the installed harnesses are choices. Each role gets its own model.
+    def add
+      harness = @prompt.choose("Harness", Flow::Models.installed) or return
+      roles = @prompt.choose_many("Roles", Maf.role_names)
+      return if roles.empty?
+
+      models = show_models(harness)
+      Maf.flow(*roles.flat_map { |role| ["--agent", agent_spec(harness, role, models)] })
+    end
+
+    private
+
+    def show_menu
+      @prompt.say("\nmaf - #{Dir.pwd}")
+      guarded { @prompt.say("Agents: #{Maf.agent_specs.join(", ").then { |s| s.empty? ? "none" : s }}") }
+      ACTIONS.each { |key, (label, _)| @prompt.say("  #{key}) #{label}") }
+      @prompt.say("  q) Quit")
+    end
+
+    def handle(answer)
+      return false if answer.nil? || answer == "q"
+
+      ACTIONS[answer] ? guarded { send(ACTIONS[answer].last) } : @prompt.say("invalid choice")
+      true
+    end
+
+    # A failed step aborts or raises. The menu prints the error and keeps running.
+    def guarded
+      yield
+    rescue SystemExit
+      nil
+    rescue StandardError => e
+      @prompt.say("error: #{e.message}")
+    end
+
+    def agent_spec(harness, role, models)
+      model = ask_model(harness, role, models).to_s
+      [harness, role, model].reject(&:empty?).join(":")
+    end
+
+    # The answer is a number of the list, a model name, or Enter for the default.
+    # A name that the harness does not list needs a confirmation: a typo makes
+    # every dispatched run fail.
+    def ask_model(harness, role, models)
+      answer = @prompt.ask("Model for #{role} (number or name, Enter = #{default_label(harness)}):").to_s
+      number = Integer(answer, exception: false)
+      return models[number - 1] if number&.between?(1, models.size)
+      return answer if answer.empty? || Flow::Models.known?(harness, answer)
+
+      @prompt.confirm?("#{harness} does not list #{answer}. Use it anyway?") ? answer : ask_model(harness, role, models)
+    end
+
+    def default_label(harness) = Flow::DEFAULT_MODELS.fetch(harness, "the harness default")
+
+    def show_models(harness)
+      models = Flow::Models.for(harness).to_a
+      @prompt.say(models.empty? ? "#{harness} lists no models. Type a name." : "Models of #{harness}:")
+      models.each_with_index { |model, i| @prompt.say("  #{i + 1}) #{model}") }
+      models
+    end
+
+    def remove
+      spec = @prompt.choose("Agent", Maf.agent_specs) or return
+      Maf.flow("--remove", spec) if @prompt.confirm?("Remove #{spec}?")
+    end
+
+    def start
+      harness, role = (@prompt.choose("Agent", Maf.agent_specs) or return).split(":")
+      worker = @prompt.ask("Worker id (Enter = default):").to_s
+      dispatch = @prompt.confirm?("Run unattended (--dispatch)?")
+      SetupAgent.run([harness, worker.empty? ? role : "#{role}_#{worker}", *("--dispatch" if dispatch)])
+    end
+
+    def roles = Maf.flow("--list-roles")
+    def update = Maf.flow
+    def uninstall = Uninstall::Runner.new(["--project", Dir.pwd]).run
+  end
+end

data/lib/maf/migrate/moves.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Maf
+  module Migrate
+    # Moves plans the move of scripts, folders, and the config file.
+    class Moves
+      def initialize(project)
+        @project = project
+      end
+
+      def steps
+        scripts + folders + config
+      end
+
+      private
+
+      def scripts
+        SCRIPTS.select { |old, _, signature| Migrate.signed?(path(old), signature) }
+               .map { |old, new, _| move(old, new) }
+      end
+
+      def folders
+        FOLDERS.select { |old, _| File.directory?(path(old)) }.map { |old, new| move(old, new) }
+      end
+
+      def config
+        File.exist?(path(".agent-flow.json")) ? [move(".agent-flow.json", ".maf/config.json")] : []
+      end
+
+      def move(old, new)
+        return Step.new("keep   #{old} (#{new} exists)", -> {}) if File.exist?(path(new))
+
+        Step.new("move   #{old} -> #{new}", -> { relocate(path(old), path(new)) })
+      end
+
+      def relocate(from, to)
+        FileUtils.mkdir_p(File.dirname(to))
+        FileUtils.mv(from, to)
+      end
+
+      def path(*parts) = File.join(@project, *parts)
+    end
+  end
+end

data/lib/maf/migrate/rewrites.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Maf
+  module Migrate
+    # Rewrites changes the old paths inside files that stay in place or move.
+    # The files are the taskrc, the worker registry, and the Claude settings.
+    class Rewrites
+      def initialize(project)
+        @project = File.realpath(project)
+      end
+
+      def steps
+        [taskrc, workers, claude_settings].compact
+      end
+
+      private
+
+      # data.location of the taskrc holds the absolute path of the task database.
+      def taskrc
+        rewrite(".maf/coordination/taskrc", [["#{@project}/coordination", "#{@project}/.maf/coordination"]])
+      end
+
+      def workers
+        rewrite(".maf/coordination/workers.json", [["#{@project}/.worktrees", "#{@project}/.maf/worktrees"]])
+      end
+
+      def claude_settings
+        rewrite(".claude/settings.json", %w[next-task board-watch].map { |name| hook_paths(name) })
+      end
+
+      def hook_paths(name)
+        ["ruby coordination/harness-hooks/#{name}.rb", "ruby .maf/coordination/harness-hooks/#{name}.rb"]
+      end
+
+      def rewrite(rel, pairs)
+        file = find(rel)
+        return unless file && pairs.any? { |old, _| File.read(file).include?(old) }
+
+        Step.new("edit   #{rel}", -> { apply(rel, pairs) })
+      end
+
+      def apply(rel, pairs)
+        file = find(rel)
+        File.write(file, pairs.reduce(File.read(file)) { |text, (old, new)| text.gsub(old, new) })
+      end
+
+      # The folder moves in an earlier step. The plan still sees the old place.
+      def find(rel)
+        [File.join(@project, rel), File.join(@project, rel.delete_prefix(".maf/"))].find { |file| File.file?(file) }
+      end
+    end
+  end
+end

data/lib/maf/migrate/role_files.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Maf
+  module Migrate
+    # RoleFiles moves the role files of the flow from the folders of the
+    # harnesses into .maf/agents/<harness>/. A file without the marker stays.
+    # The regeneration step then replaces an empty harness folder with a symlink.
+    class RoleFiles
+      def initialize(project)
+        @project = project
+      end
+
+      def steps
+        Flow::HARNESS_DIRS.flat_map { |harness, dir| files(dir).map { |file| step(harness, dir, file) } }
+      end
+
+      private
+
+      def files(dir)
+        folder = File.join(@project, dir)
+        return [] if File.symlink?(folder)
+
+        Dir.glob(File.join(folder, "*.md")).select { |file| File.read(file).include?(Bootstrap::MARKER) }
+      end
+
+      def step(harness, dir, file)
+        new = File.join(@project, ".maf", "agents", harness, File.basename(file))
+        label = "move   #{dir}/#{File.basename(file)} -> .maf/agents/#{harness}/#{File.basename(file)}"
+        return Step.new("keep   #{dir}/#{File.basename(file)} (the new file exists)", -> {}) if File.exist?(new)
+
+        Step.new(label, -> { FileUtils.mkdir_p(File.dirname(new)) && FileUtils.mv(file, new) })
+      end
+    end
+  end
+end

data/lib/maf/migrate/runner.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Maf
+  module Migrate
+    # Runner plans the migration, prints the plan, asks, and applies it.
+    class Runner
+      USAGE = "Usage: maf migrate [--check] [--yes]"
+
+      def initialize(argv)
+        @opts = {}
+        parser = OptionParser.new(USAGE) { |o| ["--project DIR", "--check", "--yes"].each { |f| o.on(f) } }
+        parser.parse!(argv, into: @opts)
+      end
+
+      def run
+        steps = plan
+        return say("nothing to migrate in #{project}") if steps.empty?
+
+        steps.each { |step| say(step.label) }
+        @opts[:check] ? say("check only; nothing moved") : apply(steps)
+      end
+
+      private
+
+      def project
+        abort USAGE unless @opts[:project] && Dir.exist?(@opts[:project])
+        @project ||= File.realpath(@opts[:project])
+      end
+
+      def plan
+        return [] unless Migrate.old_layout?(project)
+
+        [Moves, Worktrees, Rewrites, RoleFiles].flat_map { |planner| planner.new(project).steps }
+      end
+
+      def apply(steps)
+        abort "migrate: cancelled" unless @opts[:yes] || confirmed?
+        abort "migrate: a worker still runs. Stop it, then run this again." if running_workers.any?
+        steps.each(&:run)
+        regenerate
+        say("moved the flow into #{project}/.maf. Review with git status. Then commit the move.")
+      end
+
+      def confirmed?
+        print "Move the files above? [y/N] "
+        $stdin.gets.to_s.strip.match?(/\Ay(es)?\z/i)
+      end
+
+      # A dispatcher in the background keeps the old paths. The registry lists its pid.
+      def running_workers
+        paths = [".maf/coordination", "coordination"].map { |dir| File.join(project, dir, "workers.json") }
+        path = paths.find { |file| File.exist?(file) }
+        pids = path ? JSON.parse(File.read(path)).values.filter_map { |entry| entry["pid"] } : []
+        pids.select { |pid| Maf::Shared::Processes.alive?(pid) }
+      end
+
+      # Regenerate the files of the current agents: scripts, role files, symlinks,
+      # hooks, and the marked blocks. This is the same step as maf update.
+      def regenerate
+        Flow::Generator.new(["--project", project]).run if File.exist?(File.join(project, ".maf", "config.json"))
+      end
+
+      def say(message) = puts("[multi-agent-flow] #{message}")
+    end
+  end
+end

data/lib/maf/migrate/worktrees.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Maf
+  module Migrate
+    # Worktrees moves each git worktree of .worktrees/ into .maf/worktrees/.
+    # git worktree move keeps the link between the worktree and the repository.
+    # The env file of a worktree moves to .maf/env.sh with the new paths.
+    # Git excludes .maf/env.sh, so the worktree stays clean.
+    class Worktrees
+      ENV_BIN = "export MAF_BIN=%<bin>s\n" \
+                "case \":$PATH:\" in *\":$MAF_BIN:\"*) ;; *) export PATH=\"$MAF_BIN:$PATH\" ;; esac\n"
+
+      def initialize(project)
+        @project = File.realpath(project)
+      end
+
+      def steps
+        old_dirs.map do |dir|
+          new = dir.sub("/.worktrees/", "/.maf/worktrees/")
+          Step.new("move   #{rel(dir)} -> #{rel(new)} (git worktree move)", -> { move(dir, new) })
+        end
+      end
+
+      private
+
+      def old_dirs
+        root = File.join(@project, ".worktrees", "")
+        IO.popen(["git", "-C", @project, "worktree", "list", "--porcelain"], err: File::NULL, &:readlines)
+          .filter_map { |line| line[/\Aworktree (.+)/, 1] }.select { |dir| dir.start_with?(root) }
+      rescue Errno::ENOENT
+        []
+      end
+
+      def move(old, new)
+        FileUtils.mkdir_p(File.dirname(new))
+        moved = system("git", "-C", @project, "worktree", "move", old, new)
+        abort "migrate: git worktree move failed for #{old}" unless moved
+        env_file(new)
+        Dir.rmdir(File.join(@project, ".worktrees")) if Dir.empty?(File.join(@project, ".worktrees"))
+      end
+
+      # The old env file holds the absolute paths of the old coordination folder.
+      def env_file(dir)
+        old = File.join(dir, "coord-env.sh")
+        return unless File.file?(old) && File.read(old).include?("COORD_DIR=")
+
+        write_env(dir, converted(File.read(old)))
+        EnvExclude.add(dir)
+        FileUtils.rm(old)
+      end
+
+      def write_env(dir, text)
+        FileUtils.mkdir_p(File.join(dir, ".maf"))
+        File.write(File.join(dir, ".maf", "env.sh"), text)
+      end
+
+      def converted(text)
+        text.gsub("#{@project}/coordination", "#{@project}/.maf/coordination") +
+          format(ENV_BIN, bin: File.join(@project, ".maf", "bin"))
+      end
+
+      def rel(path) = path.delete_prefix("#{@project}/")
+    end
+  end
+end

data/lib/maf/migrate.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# migrate.rb - move an old-layout install of the multi-agent flow into .maf/.
+#
+# maf migrate runs Migrate::Runner. Options: --project DIR [--check] [--yes]
+#
+# Old layout: coord, dispatcher, vault, dashboard, coordination/, .worktrees/,
+# graphify-out/, obsidian/, .agent-flow.json at the project root.
+# New layout: everything in .maf/, except graphify-out/ at the root, which
+# holds the graph and the Obsidian vault (see USER_MANUAL.md).
+#
+# Moves files. Never deletes a file. Moves a script only if it carries the
+# flow signature, and a role file only if it carries the marker. If the new
+# path exists, the old file stays and the plan says so.
+# After the moves, the runner regenerates the files of the current agents,
+# like maf update.
+require "fileutils"
+require "json"
+require "optparse"
+require_relative "bootstrap"
+require_relative "flow"
+require_relative "env_exclude"
+require_relative "shared/processes"
+
+module Maf
+  module Migrate
+    # Step is one change. --check prints the label and runs nothing.
+    Step = Struct.new(:label, :work) do
+      def run = work.call
+    end
+
+    # The scripts of the old layout: [old path, new path, signature].
+    SCRIPTS = [
+      ["coord", ".maf/bin/coord", Bootstrap::COORD_SIGNATURE],
+      ["dispatcher", ".maf/bin/dispatcher", Bootstrap::DISPATCHER_SIGNATURE],
+      ["dashboard", ".maf/bin/dashboard", Bootstrap::DASHBOARD_SIGNATURE],
+      ["vault", ".maf/bin/vault", Bootstrap::VAULT_SIGNATURE],
+      ["vault-daemon", ".maf/bin/vault", Bootstrap::VAULT_SIGNATURE],
+      ["coordination/doc-graph-refresh", ".maf/bin/doc-graph-refresh", Bootstrap::DOC_GRAPH_SIGNATURE]
+    ].freeze
+
+    # The folders of the old layout: [old path, new path].
+    FOLDERS = [["coordination", ".maf/coordination"], ["obsidian", "graphify-out/obsidian"]].freeze
+
+    HINT = "This project uses the old layout. Run: maf migrate"
+
+    # True if the project has files of the old layout.
+    def self.old_layout?(project)
+      File.exist?(File.join(project, ".agent-flow.json")) ||
+        File.exist?(File.join(project, "coordination", "taskrc")) ||
+        SCRIPTS.any? { |old, _, signature| signed?(File.join(project, old), signature) }
+    end
+
+    def self.signed?(path, signature) = File.file?(path) && File.read(path).include?(signature)
+  end
+end
+
+require_relative "migrate/moves"
+require_relative "migrate/worktrees"
+require_relative "migrate/rewrites"
+require_relative "migrate/role_files"
+require_relative "migrate/runner"

data/lib/maf/prompt.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Maf
+  # Prompt asks questions on a terminal. The user picks items by number.
+  # Each question returns nil at the end of the input.
+  class Prompt
+    def initialize(input = $stdin, output = $stdout)
+      @input = input
+      @output = output
+    end
+
+    def say(text) = @output.puts(text)
+
+    def ask(question)
+      @output.print("#{question} ")
+      @input.gets&.strip
+    end
+
+    def choose(title, items)
+      show(items)
+      pick(ask("#{title}:"), items)
+    end
+
+    def choose_many(title, items)
+      show(items)
+      ask("#{title} (numbers, comma separated):").to_s.split(",").filter_map { |answer| pick(answer, items) }
+    end
+
+    def confirm?(question) = ask("#{question} [y/N]").to_s.downcase == "y"
+
+    private
+
+    def show(items) = items.each_with_index { |item, i| say("  #{i + 1}) #{item}") }
+
+    def pick(answer, items)
+      number = Integer(answer.to_s.strip, exception: false)
+      number&.between?(1, items.size) ? items[number - 1] : say("invalid choice")
+    end
+  end
+end