maf 0.1.0

data/lib/maf/bootstrap.rb

@@ -0,0 +1,162 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# bootstrap.rb - install the multi-agent coordination layer into a project.
+# flow.rb runs this file as a subprocess.
+#
+# Usage:
+#   ruby lib/maf/bootstrap.rb /path/to/project [--roles architect,backend-developer,...]
+#                                   [--check] [--install-deps] [--force]
+#
+# Idempotent: every file change is marker-guarded or content-compared, so
+# re-running never duplicates blocks and never reinstalls what is present.
+# Ruby:     3.0+ (same as coord).
+require "fileutils"
+require "json"
+require "optparse"
+
+abort "bootstrap: Ruby 3.0+ required (current: #{RUBY_VERSION}). Install with " \
+      "mise/brew: `brew install mise && mise install ruby`." if RUBY_VERSION.split(".").first.to_i < 3
+
+module Maf
+  module Bootstrap
+    MARKER = ">>> multi-agent-flow >>>"
+    END_MARKER = "<<< multi-agent-flow <<<"
+    # The one folder in the project that holds every file of the flow.
+    MAF_DIR = ".maf"
+    COORD_SIGNATURE = "coord - shared coordination layer"
+    # Older installs copied setup_agent into the project. uninstall.rb removes it.
+    SETUP_AGENT_SIGNATURE = "setup_agent - create a worktree for one agent and launch its harness session."
+    DISPATCHER_SIGNATURE = "dispatcher - task board and inbox monitor that starts one-shot agents."
+    VAULT_SIGNATURE = "vault - shared knowledge base watcher (graphify + Obsidian + MCP)."
+    DASHBOARD_SIGNATURE = "dashboard - local observability web UI for multi-agent coordination."
+    DASHBOARD_PAGE_SIGNATURE = "dashboard.html - page of the maf dashboard."
+    ANALYST_SIGNATURE = "analyst - ask a small model for token hints about one dispatched worker."
+    # The scripts in .maf/bin load the shared library from .maf/lib/maf/shared/.
+    # Its source is lib/maf/shared/. The installer gives paths relative to assets/.
+    SHARED_DIR = File.join("lib", "maf", "shared")
+    SHARED_SOURCE = File.join("..", SHARED_DIR)
+    SHARED_SIGNATURE = "maf shared library - code that the maf CLI and the scripts in .maf/bin share."
+    SUBDIRS = %w[inbox locks exports message-hooks harness-hooks].freeze
+
+    NEXT_TASK_HOOK_SIGNATURE = "next-task.rb - Stop hook for Claude Code and Codex."
+    NEXT_TASK_HERMES_SIGNATURE = "next-task-hermes.sh - on_session_end hook for Hermes Agent."
+    BOARD_WATCH_SIGNATURE = "board-watch.rb - background board watcher for Claude Code sessions."
+    SESSION_GUARD_SIGNATURE = "session-guard.rb - authorize hooks for a registered MAF session."
+    CONTEXT_WATCH_SIGNATURE = "context-watch.rb - status, usage, and context limit hook"
+    OPENCODE_BOARD_WATCH_SIGNATURE = "board-watch-opencode.js - opencode plugin that wakes an idle session"
+    OPENCODE_PLUGIN = File.join(".opencode", "plugins", "board-watch.js")
+    COMMIT_GUARD_SIGNATURE = "commit-guard - git pre-commit hook for the multi-agent flow."
+    DOC_GRAPH_SIGNATURE = "doc-graph-refresh - rebuild the knowledge graph after a markdown change."
+    ENV_SIGNATURE = "env.sh - shell environment of the multi-agent flow."
+
+    # Claude Code harness hooks: [event, hook]. The sync next-task hook continues
+    # a session at Stop. The asyncRewake board-watch hook wakes an idle session.
+    CLAUDE_HOOKS = [
+      ["SessionStart", { "type" => "command", "command" => "ruby .maf/coordination/harness-hooks/next-task.rb" }],
+      ["Stop", { "type" => "command", "command" => "ruby .maf/coordination/harness-hooks/next-task.rb" }],
+      *%w[SessionStart Stop].map do |event|
+        [event, { "type" => "command", "command" => "ruby .maf/coordination/harness-hooks/context-watch.rb" }]
+      end,
+      *%w[SessionStart Stop].map do |event|
+        [event, { "type" => "command", "command" => "ruby .maf/coordination/harness-hooks/board-watch.rb",
+                  "async" => true, "asyncRewake" => true, "timeout" => 604_800 }]
+      end
+    ].freeze
+
+    # The knowledge graph and the Obsidian vault, at the project root where graphify looks by default.
+    GRAPH_DIR = "graphify-out"
+
+    # The paths that every install excludes from git. AgentLinks and CodexHooks
+    # add the harness paths they create. The graph entry has no trailing slash,
+    # so it also hides the graph symlink in each worktree.
+    EXCLUDED = [".maf/", "/#{GRAPH_DIR}", OPENCODE_PLUGIN].freeze
+
+    # The Claude Code settings of the flow. `maf start` passes them with --settings,
+    # so the project's .claude/settings.json stays as it is.
+    CLAUDE_SETTINGS = File.join(MAF_DIR, "claude", "settings.json")
+
+    # Maps each writing action kind to the Installer method that performs it.
+    # Every writer takes (path, source). :skip and :refuse write nothing.
+    WRITERS = { mkdir: :make_dir, touch: :touch_file, create: :write_script, update: :write_script,
+                create_taskrc: :write_taskrc, upgrade_taskrc: :upgrade_taskrc,
+                local_exclude: :write_exclude,
+                configure_claude_hook: :configure_claude_settings, merge_hook: :merge_hook }.freeze
+
+    REQUIRED_DEPS = {
+      "task" => {
+        why: "Taskwarrior, the task board backend",
+        install: -> { system("brew", "install", "task") }
+      }
+    }.freeze
+
+    OPTIONAL_DEPS = {
+      "graphify" => "knowledge graph (pip/uv install graphifyy)"
+    }.freeze
+
+    NEXT_STEPS = <<~TEXT
+      Next steps (run inside %{project}):
+
+        1. Verify:
+             cd %{project} && source .maf/env.sh && coord init && coord status
+
+        2. Set COORD_ROLE and COORD_WORKER so messages and locks are attributed, e.g.:
+             export COORD_ROLE=local COORD_WORKER=local-1
+
+        3. Shared memory (graphify + Obsidian vault): %{vault_note}
+
+        4. Serialize local generation on the shared model host:
+             coord with-lock ollama -- <command>
+
+      Requested roles: %{roles}
+
+      The task board lives in %{project}/.maf/coordination/taskdata (project-local),
+      not in your global Taskwarrior database. Point `task` at it directly with:
+        TASKRC=%{project}/.maf/coordination/taskrc task ...
+    TEXT
+
+    MIGRATION_NOTE = <<~TEXT
+
+      [multi-agent-flow] NOTE: found the multi-agent-flow UDA block in your
+      global %{taskrc}. Older versions of this installer shared one Taskwarrior
+      database across every project. This install now uses a project-local
+      database instead (%{project}/.maf/coordination/taskdata) and does not touch
+      %{taskrc}.
+
+      Tasks already in the global database are NOT moved automatically. To
+      bring old tasks into this project:
+        TASKRC=%{taskrc} task export project:%{project_name} > /tmp/old-tasks.json
+        TASKRC=%{project}/.maf/coordination/taskrc task import /tmp/old-tasks.json
+      (adjust the `project:` filter to however the old tasks are tagged.)
+    TEXT
+
+    def self.say(message)
+      puts "[multi-agent-flow] #{message}"
+    end
+
+    def self.which(bin)
+      ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, bin)) }
+    end
+  end
+end
+
+require_relative "local_exclude"
+require_relative "shared/git_identity"
+require_relative "bootstrap/marked_block"
+require_relative "bootstrap/options"
+require_relative "bootstrap/dependencies"
+require_relative "bootstrap/project"
+require_relative "bootstrap/global_taskrc_warning"
+require_relative "bootstrap/layout_planner"
+require_relative "bootstrap/script_planner"
+require_relative "bootstrap/git_hook_planner"
+require_relative "bootstrap/text_planner"
+require_relative "bootstrap/claude_settings"
+require_relative "bootstrap/hook_merger"
+require_relative "bootstrap/writer"
+require_relative "bootstrap/graph_home"
+require_relative "bootstrap/memory_branch"
+require_relative "bootstrap/vault_starter"
+require_relative "bootstrap/installer"
+
+Maf::Bootstrap::Installer.new(ARGV).run if __FILE__ == $PROGRAM_NAME

data/lib/maf/budget.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# budget.rb - team limits for maf prepare.
+require "json"
+
+module Maf
+  # Budget reads the "team" key of .maf/config.json:
+  #   "team": { "max_workers": 6, "allow": ["claude", "opencode:deepseek/deepseek-v4-flash"] }
+  # max_workers does not count the project manager. An "allow" entry without
+  # a model allows every model of that harness. Without "team", maf sets no limits.
+  class Budget
+    LEAD = "project-manager"
+
+    def self.at(root)
+      path = File.join(root, ".maf/config.json")
+      new(team(path))
+    end
+
+    # A corrupt manifest must not silently drop the budget: without limits,
+    # maf would start every worker. Stop with a clear message instead.
+    def self.team(path)
+      return {} unless File.exist?(path)
+
+      JSON.parse(File.read(path)).fetch("team", {})
+    rescue JSON::ParserError
+      abort "maf: #{path} is not valid JSON. Fix it, then run this command again."
+    end
+
+    def initialize(team)
+      @max = team["max_workers"]
+      @allow = team.fetch("allow", [])
+    end
+
+    # With exactly one allowed model for the harness, maf uses that model.
+    def default_model(harness)
+      models = @allow.map { |spec| spec.split(":", 2) }.select { |name, _| name == harness }.map(&:last)
+      models.size == 1 ? models.first : nil
+    end
+
+    def check!(harness, model, count)
+      abort "maf: #{[harness, model].compact.join(":")} is not allowed. Allowed: #{@allow.join(", ")}" \
+        unless allowed?(harness, model)
+      abort "maf: the team would have #{count} workers. max_workers is #{@max}. Retire a worker first." \
+        if @max && count > @max
+    end
+
+    def allowed?(harness, model)
+      @allow.empty? || @allow.any? { |spec| [harness, "#{harness}:#{model}"].include?(spec) }
+    end
+
+    def count(workers) = workers.count { |_id, entry| entry["role"] != LEAD }
+
+    def summary
+      max = @max ? "max_workers #{@max}" : "no worker limit"
+      allow = @allow.empty? ? "every harness" : @allow.join(", ")
+      "Budget: #{max}. Allowed: #{allow}. The project manager does not count."
+    end
+  end
+end

data/lib/maf/cli.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+# Maf::CLI maps maf subcommands to the installer code. The project is always
+# the current directory.
+require "json"
+require "yaml"
+require_relative "flow"
+require_relative "uninstall"
+require_relative "migrate"
+require_relative "setup_agent"
+require_relative "menu"
+require_relative "team"
+require_relative "team_command"
+require_relative "worker_control"
+require_relative "untrack"
+require_relative "version"
+
+module Maf
+  MANIFEST = ".maf/config.json"
+
+  def self.flow(*args) = Flow::Generator.new(["--project", Dir.pwd, *args]).run
+  def self.role_names = Flow::RoleCatalog.new(Dir.pwd).roles.keys
+
+  def self.agents = File.exist?(MANIFEST) ? JSON.parse(File.read(MANIFEST)).fetch("agents") : []
+  def self.agent_specs = agents.map { |a| "#{a["harness"]}:#{a["role"]}" }
+
+  # AgentArgs turns the bare HARNESS:ROLE arguments of add and remove into
+  # flow.rb flags. Flag values (for example --model ROLE=MODEL) stay as they are.
+  module AgentArgs
+    def self.convert(args, flag)
+      args.each_with_index.flat_map { |arg, i| spec?(arg, i.zero? ? nil : args[i - 1]) ? [flag, arg] : [arg] }
+    end
+
+    def self.spec?(arg, before) = !arg.start_with?("-") && !value_flags.include?(before)
+    def self.value_flags = @value_flags ||= Flow::Generator.value_flags
+  end
+
+  class CLI
+    COMMANDS = {
+      "add" => "[HARNESS:ROLE[:MODEL] ...] [--model ROLE=MODEL]  add agents and install the flow; " \
+               "without arguments it asks",
+      "remove" => "HARNESS:ROLE ...                        remove agents",
+      "update" => "                                        regenerate the files of the current agents",
+      "agents" => "                                        list the current agents",
+      "roles" => "                                        list the built-in roles and the project roles",
+      "role" => "add NAME                                add a stub role to .maf/roles.yml",
+      "start" => "[HARNESS ROLE[_WORKER]] [--dispatch [--detach]]  start one agent in its worktree",
+      "prepare" => "HARNESS ROLE[_WORKER] [--dispatch|--interactive] [--replace W]  prepare a worker; " \
+                   "--dispatch starts it (default for the architect)",
+      "retire" => "ROLE[_WORKER]                           remove a worker; its tasks return to the pool",
+      "worker" => "status|stop|start|restart ROLE[_WORKER] [--force] [--max-context N] [--max-session-runs N] " \
+                  "[--cache-window S]  control one worker; start and restart save the session limits of the role",
+      "team" => "[set --max N --allow HARNESS[:MODEL]]   show the team, or set its budget",
+      "uninstall" => "[--check] [--yes] [--force]             remove the flow from the project",
+      "migrate" => "[--check] [--yes]                       move an old-layout install into .maf/",
+      "untrack" => "[--check] [--yes]                       remove the flow from git; the files stay (then commit)",
+      "menu" => "                                        interactive mode (also: maf without a command)",
+      "guide" => "                                        print the setup guide for an AI agent (install.md)",
+      "version" => "                                        print the maf version (also: --version)"
+    }.freeze
+
+    def initialize(argv)
+      @command, *@args = argv
+      @command = "version" if %w[-v --version].include?(@command)
+    end
+
+    def run
+      return run_menu if @command.nil? && $stdin.tty?
+      return help if @command.nil? || %w[help -h --help].include?(@command)
+      abort "maf: unknown command '#{@command}'. Run: maf help" unless COMMANDS.key?(@command)
+      abort "maf: #{Migrate::HINT}" if old_layout?
+
+      send("run_#{@command}")
+    end
+
+    private
+
+    # Every command except these needs the new layout.
+    # maf uninstall --check previews the migration on an old layout.
+    def old_layout?
+      return false if %w[migrate roles menu guide version].include?(@command) || uninstall_check?
+
+      Migrate.old_layout?(Dir.pwd)
+    end
+
+    def uninstall_check? = @command == "uninstall" && @args.include?("--check")
+
+    def help
+      puts "Usage: maf COMMAND [ARGS]   (run in the project root)", ""
+      COMMANDS.each { |name, text| puts "  maf #{name.ljust(10)}#{text}" }
+    end
+
+    # Without arguments on a terminal, maf add asks for the harness, the roles, and the models.
+    def run_add = @args.empty? && $stdin.tty? ? Menu.new.add : Maf.flow(*AgentArgs.convert(@args, "--agent"))
+    def run_remove = Maf.flow(*AgentArgs.convert(@args, "--remove"))
+    def run_update = Maf.flow(*@args)
+    def run_roles = Maf.flow("--list-roles")
+
+    def run_role
+      abort "usage: maf role add NAME" unless @args.first == "add" && @args[1]
+
+      added = Flow::RoleStub.new(Dir.pwd, @args[1]).add == :create
+      puts(added ? "Role added: #{Flow::RoleCatalog::FILE}. Fill in the TODO lines." : "Role exists: #{@args[1]}")
+    end
+    def run_start = @args.empty? ? SetupAgent.run_here : SetupAgent.run(@args)
+    def run_prepare = Prepare.new(@args).run
+    def run_team = TeamCommand.new(@args, SetupAgent::Project.root).run
+    def run_worker
+      spec = @args[1] || abort(worker_usage)
+      limits = RoleLimits.parse(@args)
+      WorkerControl.new(SetupAgent::Project.root, spec, force: @args.include?("--force"), limits: limits)
+        .run(@args[0].to_s)
+    end
+
+    def worker_usage = "usage: maf worker #{WorkerControl::ACTIONS.join("|")} ROLE[_WORKER] [--force] " \
+                       "[--max-context N] [--max-session-runs N] [--cache-window S]"
+    def run_retire = Retire.new(SetupAgent::Project.root, @args.first || abort("usage: maf retire ROLE[_WORKER]")).run
+    def run_uninstall = Uninstall::Runner.new(["--project", Dir.pwd, *@args]).run
+    def run_menu = Menu.new.run
+    def run_guide = puts(File.read(File.join(Flow::ROOT, "install.md")))
+    def run_version = puts("maf #{VERSION}")
+    def run_untrack = Untrack.new(SetupAgent::Project.root, @args).run
+    def run_migrate = Migrate::Runner.new(["--project", Dir.pwd, *@args]).run
+
+    def run_agents
+      return puts("No agents yet. Add one: maf add HARNESS:ROLE") if Maf.agents.empty?
+
+      Maf.agents.each { |a| puts agent_line(a) }
+    end
+
+    def agent_line(agent)
+      "#{agent["harness"]}:#{agent["role"]}".ljust(32) + agent["model"].to_s
+    end
+  end
+end

data/lib/maf/env_exclude.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "shared/git_exclude"
+
+module Maf
+  # EnvExclude hides the .maf/env.sh of a worktree from git.
+  # .maf/env.sh holds absolute host paths and must never be committed.
+  # Git has no per-worktree exclude, so add the path to the shared local exclude.
+  # coord worktree does the same (see Coord::Worktree#exclude_env_file).
+  # An excluded file does not block git worktree remove.
+  module EnvExclude
+    FILE = ".maf/env.sh"
+
+    def self.add(dir)
+      path = Maf::Shared::GitExclude.path(dir)
+      return if path.nil? || (File.exist?(path) && File.read(path).lines.map(&:strip).include?(FILE))
+
+      FileUtils.mkdir_p(File.dirname(path))
+      File.open(path, "a") { |file| file.puts(FILE) }
+    end
+  end
+end

data/lib/maf/flow/agent_links.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # AgentLinks makes the folder of each harness a relative symlink into
+    # .maf/agents/<harness>/. The harness reads its role files there. Each
+    # link goes into the local git exclude: the flow is not a part of the project.
+    class AgentLinks
+      def initialize(project)
+        @project = project
+      end
+
+      # Returns :create, :skip, or :refuse. :refuse means the folder holds files
+      # that the flow does not own, or a symlink to another place.
+      def link(harness)
+        path = File.join(@project, HARNESS_DIRS.fetch(harness))
+        return exclude(path) && :skip if linked?(path, harness)
+        return :refuse unless free?(path)
+
+        make(path, harness)
+      end
+
+      def self.target(harness)
+        File.join("..", MAF_DIR, "agents", harness)
+      end
+
+      # A harness folder with the user's own files stays. Each role file gets a
+      # relative symlink in it instead, so the harness still finds the role.
+      # A user file with the same name stays, and its name is returned.
+      def link_files(harness)
+        dir = File.join(@project, HARNESS_DIRS.fetch(harness))
+        prune(dir, harness)
+        role_files(harness).reject { |source| link_file(dir, source) }.map { |source| File.basename(source) }
+      end
+
+      def self.file_target(harness, name) = File.join("..", "..", MAF_DIR, "agents", harness, name)
+
+      private
+
+      def linked?(path, harness)
+        File.symlink?(path) && File.readlink(path) == self.class.target(harness)
+      end
+
+      def free?(path)
+        return true unless File.exist?(path) || File.symlink?(path)
+
+        File.directory?(path) && !File.symlink?(path) && Dir.empty?(path)
+      end
+
+      def role_files(harness) = Dir.glob(File.join(@project, MAF_DIR, "agents", harness, "*.md")).sort
+
+      def link_file(dir, source)
+        path = File.join(dir, File.basename(source))
+        target = self.class.file_target(File.basename(File.dirname(source)), File.basename(source))
+        # A link of an older install is in git status until it is excluded.
+        return File.readlink(path) == target && exclude(path) if File.symlink?(path)
+
+        !File.exist?(path) && File.symlink(target, path) && exclude(path)
+      end
+
+      def exclude(path) = LocalExclude.add(@project, path.delete_prefix("#{@project}/")) || true
+
+      # A link of a removed role points nowhere. Remove it.
+      def prune(dir, harness)
+        prefix = File.join("..", "..", MAF_DIR, "agents", harness, "")
+        Dir.glob(File.join(dir, "*.md")).each do |path|
+          File.delete(path) if File.symlink?(path) && File.readlink(path).start_with?(prefix) && !File.exist?(path)
+        end
+      end
+
+      def make(path, harness)
+        Dir.rmdir(path) if File.directory?(path)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.symlink(self.class.target(harness), path)
+        exclude(path) && :create
+      end
+    end
+  end
+end

data/lib/maf/flow/bootstrapper.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # Bootstrapper runs bootstrap.rb, which installs the board, the scripts,
+    # and the hooks in the project.
+    class Bootstrapper
+      def initialize(options)
+        @options = options
+      end
+
+      def run
+        return if !@options.bootstrap? || @options.check?
+
+        make_harness_dirs
+        abort "flow: coordination bootstrap failed" unless system(*command)
+      end
+
+      private
+
+      # Bootstrap adds the Claude Code hooks only if .claude/ exists, and the
+      # opencode plugin only if .opencode/ exists. Flow writes the role files
+      # after bootstrap, so create these dirs first.
+      def make_harness_dirs
+        used = %w[claude opencode] & @options.agents.map { |a| a[:harness] }
+        used.each { |harness| FileUtils.mkdir_p(File.join(@options.project, ".#{harness}")) }
+      end
+
+      def command
+        roles = @options.agents.map { |a| a[:role] }.uniq.join(",")
+        args = [RbConfig.ruby, File.join(__dir__, "..", "bootstrap.rb"), @options.project, "--roles", roles]
+        @options.force? ? args << "--force" : args
+      end
+    end
+  end
+end

data/lib/maf/flow/codex_hooks.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # Install hooks in the project. Preserve other hook definitions.
+    class CodexHooks
+      HOOKS_DIR = '"$(git rev-parse --show-toplevel)/.maf/coordination/harness-hooks'
+      COMMANDS = %w[next-task.rb context-watch.rb].map { |name| %(ruby #{HOOKS_DIR}/#{name}") }.freeze
+      EVENTS = %w[SessionStart Stop].freeze
+      FILE = ".codex/hooks.json"
+      TIMEOUT = { "timeout" => 3600 }.freeze
+
+      def initialize(project)
+        @project = project
+        @path = File.join(project, FILE)
+      end
+
+      def install
+        data = File.exist?(@path) ? JSON.parse(File.read(@path)) : {}
+        EVENTS.product(COMMANDS).each { |event, command| add(data, event, command) }
+        save(data)
+        LocalExclude.add(@project, FILE) unless tracked?
+      end
+
+      private
+
+      def save(data)
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, JSON.pretty_generate(data))
+      end
+
+      # A project that tracks its own Codex hooks keeps the file in git.
+      def tracked?
+        system("git", "-C", @project, "ls-files", "--error-unmatch", FILE, out: File::NULL, err: File::NULL)
+      end
+
+      def add(data, event, command)
+        entries = (data["hooks"] ||= {})[event] ||= []
+        found = entries.flat_map { |entry| entry.fetch("hooks", []) }.find { |hook| hook["command"] == command }
+        found ? found.merge!(hook(command)) : entries << { "hooks" => [hook(command)] }
+      end
+
+      # After `coord await`, next-task.rb waits for work for up to 55 minutes.
+      # Without a timeout, Codex could stop the hook before work arrives.
+      def hook(command)
+        { "type" => "command", "command" => command }.merge(command.include?("next-task.rb") ? TIMEOUT : {})
+      end
+    end
+  end
+end

data/lib/maf/flow/generator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # Generator runs one maf add, remove, update, or roles command.
+    class Generator
+      # Flags that take a value. maf uses them to tell flag values from agent specs.
+      def self.value_flags = Options.new([]).value_flags
+
+      def initialize(argv)
+        @options = Options.new(argv)
+      end
+
+      def run
+        prepare
+        return print_roles if @options.list_roles
+
+        Validator.new(@options, @roles).run
+        @options.agents.empty? ? finish_without_agents : generate_all
+      end
+
+      private
+
+      def prepare
+        @options.parse
+        Validator.project!(@options)
+        @catalog = RoleCatalog.new(@options.project)
+        @roles = @catalog.roles
+      end
+
+      def generate_all
+        Bootstrapper.new(@options).run
+        results = RoleFiles.new(@options, @roles).generate
+        HarnessLinker.new(@options).run
+        McpInstaller.new(@options).install
+        finish(results)
+      end
+
+      def finish(results)
+        pending = @options.check? ? false : HookInstaller.new(@options.agents, @options.project).install
+        manifest.write
+        Report.new(@options.project, @roles, pending).print(results)
+      end
+
+      def manifest = Manifest.new(@options, @roles)
+
+      def print_roles
+        puts "Available roles (model_hint is a recommendation only):"
+        @roles.each { |key, data| print_role(key, data) }
+      end
+
+      def print_role(key, data)
+        puts "", "  #{key} (#{@catalog.source(key)})", "    #{data.fetch("description")}",
+             "    model hint: #{data.fetch("model_hint")}"
+      end
+
+      def finish_without_agents
+        manifest.write
+        puts "No agents left. Add one: maf add HARNESS:ROLE. Remove the flow: maf uninstall."
+      end
+    end
+  end
+end

data/lib/maf/flow/harness_linker.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # HarnessLinker points the folder of each harness at the role files in
+    # .maf/agents/. A folder with the user's own files gets one link per role.
+    class HarnessLinker
+      def initialize(options)
+        @options = options
+        @links = AgentLinks.new(options.project)
+      end
+
+      def run
+        return if @options.check?
+
+        harnesses.each { |harness| link_role_files(harness) if @links.link(harness) == :refuse }
+      end
+
+      private
+
+      def harnesses = @options.agents.map { |a| a[:harness] }.uniq.select { |h| HARNESS_DIRS.key?(h) }
+      def dir(harness) = HARNESS_DIRS.fetch(harness)
+
+      def link_role_files(harness)
+        return warn_not_linked(harness) if File.symlink?(File.join(@options.project, dir(harness)))
+
+        kept = @links.link_files(harness)
+        warn "flow: #{dir(harness)} has own files named #{kept.join(", ")}. Those roles are not linked." if kept.any?
+      end
+
+      def warn_not_linked(harness)
+        warn "flow: #{dir(harness)} points to another folder. " \
+             "The #{harness} harness cannot read the role files. Run: maf migrate"
+      end
+    end
+  end
+end