maf 0.1.0

data/install.md

@@ -0,0 +1,326 @@
+# Multi-agent flow - installation instruction
+
+This file is an instruction for an AI coding agent. Read the whole file. Then do
+the steps in order.
+
+You set up a shared coordination layer for multiple coding agents in one project.
+
+---
+
+## Step 1 - Install the maf command
+
+Check the tools. `maf` and the `coord` tool are Ruby scripts.
+
+```sh
+ruby -v
+git --version
+task --version
+```
+
+If Ruby is older than 3.0, stop. Tell the user to install Ruby 3.0 or later.
+If `task` is missing, install it. On macOS, run `brew install task`.
+On Linux, run `sudo apt-get install taskwarrior`.
+
+Install the maf gem:
+
+```sh
+gem install maf
+maf version
+```
+
+If `maf version` works already, do not install the gem again.
+If `maf version` fails after the install, add the gem bin folder to `PATH`.
+`gem env` shows the folder under EXECUTABLE DIRECTORY.
+
+The flow folder holds the templates. Call that folder `FLOW`:
+
+```sh
+export FLOW="$(dirname "$(dirname "$(gem which maf)")")"
+ls "$FLOW/templates"
+```
+
+If maf runs from a clone of the repository, `FLOW` is the clone folder.
+
+## Step 2 - Ask the user for the project folder
+
+Ask: "Which project folder should use the multi-agent flow?"
+
+Use the answer as `PROJECT`. The folder must exist and must be a git repository.
+Run all `maf` commands below in `PROJECT`:
+
+```sh
+cd "$PROJECT"
+```
+
+## Step 3 - Ask the user for harnesses and roles
+
+Ask: "Which agent harnesses do you want to use? For example: opencode, Claude
+Code, Codex, Hermes."
+
+Show the available roles. Run:
+
+```sh
+maf roles
+```
+
+Tell the user about the `project-manager` role: the user talks to it, it sends
+goals to the architect (`coord goal add`), and the architect reports back to it.
+Recommend it whenever the architect would otherwise take requests directly
+from the user. Ask the user to map roles to harnesses. Example answer:
+
+- claude -> project-manager
+- claude -> architect
+- opencode -> backend-developer
+- opencode -> frontend-developer
+- codex -> reviewer
+- hermes -> tester
+
+You may run more than one role in one harness. Open one session per role.
+
+## Step 3b - Ask the user for the number of workers
+
+Ask: "How many workers do you want for each worker role?"
+
+A worker role is a role other than `project-manager` and `architect`.
+Default: one worker per role.
+Remember the answer. Step 7 uses it for the `maf start` commands.
+
+## Step 3c - Ask the user for custom roles
+
+Ask: "Do you need a role that is not in the list? Describe it in one sentence."
+
+If the user needs no custom role, skip this step.
+If the user needs a custom role, do these steps for each role:
+
+1. Run `maf role add NAME`. The command writes a stub into `.maf/roles.yml`.
+2. Replace each `TODO` line in the stub. Use the four duty parts: focus,
+   checks, done condition, and avoid. Write them in Simplified Technical English.
+3. Use `NAME` as a role in Step 5.
+
+A role in `.maf/roles.yml` with the name of a built-in role replaces the built-in role.
+`maf roles` shows the source of each role.
+
+## Step 3d - Ask the user for the workflow
+
+The workflow tells the architect in which order to create tasks.
+Ask: "Which workflow do you want? Choose one, or describe your own in your own words."
+
+| Name | Stages |
+|---|---|
+| `simple` | Implement, review, merge. |
+| `plan-review` | Plan, review the plan, implement, review, merge. |
+| `tdd` | Plan, review the plan, write specs, implement, review, merge. |
+| `panel` | Plan, three reviewers attack the plan, implement, review, three reviewers attack the goal diff, merge. |
+
+If the user chooses `panel`, add the roles `reviewer`, `skeptic`, and `auditor` in Step 5.
+The three roles review the same plan and the same goal diff. Each role checks a different area.
+
+If the user chooses a name, copy the file `FLOW/templates/workflows/<name>.md`
+to `.maf/workflow.md`.
+If the user describes a workflow, write the description to `.maf/workflow.md` as
+stage instructions. Use Simplified Technical English. Write one instruction per
+sentence. Write "Stage N." at the start of each stage. State the gate that ends
+each stage. Do not create tasks for a stage in advance: the architect creates
+the tasks of the next stage after the gate passes.
+If the user wants no workflow, create no `.maf/workflow.md`.
+
+Only the architect reads `.maf/workflow.md`. Other roles do not see it.
+Run `maf update` after each later change of the file.
+Step 5 reads `.maf/roles.yml` and `.maf/workflow.md`, so write both before Step 5.
+
+## Step 4 - Ask the user for a model per role
+
+Do not choose models yourself. Ask the user.
+
+Show the model hint from step 3 for each role. Explain that the hint is only a
+recommendation. The user knows what runs on the machine.
+
+The user may skip a model. If skipped, the harness default applies.
+
+If the workflow is `panel`, propose a different model family for each of
+`reviewer`, `skeptic`, and `auditor`. Example: Claude, GPT, and Gemini.
+Different models miss different defects. The user makes the final choice.
+
+## Step 5 - Add the agents
+
+Give one `HARNESS:ROLE` argument per role. Add one `--model ROLE=MODEL` flag
+per chosen model.
+
+Preview first. This writes nothing.
+
+```sh
+maf add claude:project-manager claude:architect \
+  opencode:backend-developer opencode:frontend-developer \
+  codex:reviewer hermes:tester \
+  --model project-manager=claude-opus-5-5 \
+  --model architect=claude-opus-5-5 \
+  --check
+```
+
+Then run the same command without `--check`.
+
+`maf add` does these things:
+
+1. Sets up the coordination layer.
+2. Writes a role file for each role, in the format of its harness.
+3. Writes a manifest at `$PROJECT/.maf/config.json`.
+4. Writes the graphify MCP server into `.maf/mcp/` for Claude Code and opencode.
+   `maf start` passes the file to the harness. The project's `.mcp.json` and `opencode.json` stay as they are.
+   For Codex and Hermes, `maf add` prints a command. Run it to add the server.
+   To turn the server off, set `"mcp": false` in `.maf/config.json`.
+
+`maf add` is idempotent. It skips files that are already correct.
+
+## Step 5b - Turn on the Hermes hook (Hermes roles only)
+
+Skip this step when no role uses the Hermes harness.
+
+`maf add` installs the hook script at `~/.hermes/agent-hooks/next-task.sh`.
+Hermes runs it when a session ends. The hook resumes the session when the role
+has unclaimed tasks.
+
+The hook stays inactive until the Hermes config declares it and the user
+approves it. `maf add` prints the commands. Run them in order.
+
+```sh
+hermes config set hooks.on_session_end '[{"command":"<script path>","timeout":30}]'
+hermes chat --oneshot --accept-hooks -q ok
+hermes hooks doctor
+```
+
+Do not edit `~/.hermes/config.yaml` by hand. The file holds comments and markers
+that a rewrite destroys.
+
+The first command replaces the whole `on_session_end` list. If the list is not
+empty, read it first with `hermes config get hooks.on_session_end`. Then set the
+list with the existing entries plus the new entry.
+
+The second command approves the hook one time. Hermes stores the consent for this
+version of the script. A new script version needs a new approval.
+
+Confirm that every check from `hermes hooks doctor` passes. Then continue.
+
+## Step 5c - Set the Gemini key for the doc-graph refresh
+
+`maf add` appends a flow block to the `post-commit` and `post-merge` git hooks.
+A markdown commit or merge starts `.maf/bin/doc-graph-refresh` detached.
+The script runs `graphify extract . --backend gemini` and re-exports
+`graphify-out/obsidian/`. It needs `GEMINI_API_KEY`:
+
+```sh
+export GEMINI_API_KEY=<key>
+```
+
+The hook starts no LLM call without the key. It logs a skip in
+`.maf/coordination/doc-graph.log`. The hook never fails a commit.
+
+## Step 6 - Verify
+
+```sh
+cd "$PROJECT"
+source .maf/env.sh
+coord init
+coord status
+maf agents
+```
+
+`source .maf/env.sh` puts `.maf/bin` on `PATH`, so the shell finds `coord`.
+
+Check that each role file exists:
+
+- opencode: `.opencode/agents/<role>.md`
+- Claude Code: `.claude/agents/<role>.md`
+- Codex: `.codex/prompts/<role>.md`
+- Hermes: `~/.hermes/skills/<project-name>-<role>/SKILL.md` (namespaced by
+  project; Hermes skills are global, so this keeps two projects with the
+  same role from overwriting each other's skill)
+
+## Step 6b - Do not commit the flow
+
+maf is a tool, not a part of the project. It lists `.maf/` and its links in
+`.git/info/exclude`, so `git status` shows no maf file. Do not commit them.
+The project needs at least one commit, because each worker worktree starts from a commit.
+
+If `git ls-files .maf` lists files, an older maf version committed them. Run
+`maf untrack`, review `git status`, and ask the user to commit the result.
+
+## Step 7 - Report to the user
+
+Report the generated files. Then print one `maf start` command for each worker.
+Use the number of workers from Step 3b. A worker role with N workers gets the
+names `ROLE_1` to `ROLE_N`. A role with one worker may use the bare role name.
+Then give the user these instructions.
+
+> For each claude, opencode, or codex agent, open a terminal in the project
+> folder and run:
+>
+>     maf start HARNESS ROLE[_WORKER] [model:PROVIDER/MODEL]
+>
+> Example, for this setup:
+>
+>     maf start claude project-manager
+>     maf start claude architect
+>     maf start opencode backend-developer_1
+>     maf start opencode frontend-developer_1
+>     maf start codex reviewer
+>
+> To run an agent unattended, add `--dispatch`. The agent then starts only
+> when there is work, and it exits when the work is done:
+>
+>     maf start hermes tester --dispatch
+>
+> The architect never talks to the user. Run it with `--dispatch` unless the
+> user wants to watch it: `maf start claude architect --dispatch`.
+>
+> This creates (or reuses) a worktree at `.maf/worktrees/<role>-<worker_id>`,
+> sets `COORD_ROLE` and `COORD_WORKER`, and launches the harness there with
+> its role loaded. To run several instances of one role, add a worker suffix:
+> `backend-developer_1`, `backend-developer_2`. Claims are atomic, so they
+> will not collide.
+>
+> Hermes loads the role as a skill (`--skills <project>-<role>`); the skill
+> file at `~/.hermes/skills/<project>-<role>/SKILL.md` must have been generated
+> by `maf add` first.
+>
+> Talk to the project manager session, not the architect. For example: "Build a
+> task tracker app." The project manager sends the goal to the architect. The
+> architect creates tasks. The workers pick them up. The architect reports back
+> to the project manager, and the project manager reports back to you. If no
+> `project-manager` role was set up, talk to the architect session directly
+> instead.
+
+## Domain documentation
+
+Do not create `GLOSSARY.md` at install time. The project has no terms yet.
+The project manager creates the first draft when the first term resolves.
+The architect owns `GLOSSARY.md`. A worker that can edit files commits it on the goal branch.
+Tell the user this in the report of Step 7.
+Do not add a `GLOSSARY-MAP.md` unless the project has more than one bounded context.
+ADRs use the decisions folder: `.agent/decisions/` if it exists, else `docs/decisions/`.
+
+## Notes
+
+- One writer per path. The task scope defines the paths. `coord add`/`conflicts`
+  warns on overlap; roles with `can_edit: false` also get a restricted tool grant
+  where the harness supports one (Claude Code, opencode, Hermes), and the git
+  `pre-commit` guard refuses their commits.
+- Every generated role file requires Simplified Technical English in
+  `coord msg`, `coord annotate`, and task titles: one instruction per
+  sentence, active voice, named subject, no idioms.
+- Take the `ollama` lock before a local model generation:
+  `coord with-lock ollama -- <command>`.
+- Give each agent its own worktree so file changes never collide:
+  `coord worktree <role>` creates `.maf/worktrees/<role>-<worker_id>` (inside the
+  project, excluded from git) on branch `worker/<role>-<worker_id>`. In that worktree
+  run `source .maf/env.sh` first; it points `COORD_DIR` and `TASKRC` at the
+  main project, so every worktree shares one .maf/coordination/ dir and one task
+  board. `maf start` does all of this for you.
+- Claude Code does not auto-load `.claude/agents/<role>.md` into an interactive
+  session (that file is a subagent definition, used via its Task tool, not the
+  session's own persona). `maf start claude <role>` works around this by
+  passing an initial prompt that tells the session to read and follow it.
+- The user can add agents later with `maf add HARNESS:ROLE`.
+  The user can remove agents with `maf remove HARNESS:ROLE`.
+  `maf add` keeps the current agents.
+- Codex and Hermes have no subagent files. Codex gets custom prompts. Hermes gets
+  skills, loaded via `--skills <project>-<role>`. Both work the same way in this flow.

data/lib/maf/bootstrap/claude_settings.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Maf
+  module Bootstrap
+    # ClaudeSettings plans and applies the Claude Code hooks in the settings
+    # file of the flow, .maf/claude/settings.json. `maf start` passes the file
+    # with --settings. Claude Code runs these hooks next to the project's own.
+    class ClaudeSettings
+      def initialize(project)
+        @project = project
+      end
+
+      def plan
+        file = @project.path(CLAUDE_SETTINGS)
+        [@project.action(status(file), file, "#{file} (next-task + board-watch hooks)", :claude_stop_hook)]
+      end
+
+      def configure(file)
+        settings = read(file)
+        missing = missing_hooks(settings)
+        missing.each { |event, hook| add_hook(settings, event, hook) }
+        write(file, settings) unless missing.empty?
+        !missing.empty?
+      end
+
+      private
+
+      def status(file)
+        File.exist?(file) && missing_hooks(read(file)).empty? ? :skip : :configure_claude_hook
+      end
+
+      def read(file)
+        File.exist?(file) ? (JSON.parse(File.read(file)) rescue {}) : {}
+      end
+
+      def missing_hooks(settings)
+        CLAUDE_HOOKS.reject { |event, hook| hook_entry?(settings, event, hook["command"]) }
+      end
+
+      def hook_entry?(settings, event, command)
+        (settings.dig("hooks", event) || []).any? { |entry| entry.dig("hooks", 0, "command") == command }
+      end
+
+      def add_hook(settings, event, hook)
+        settings["hooks"] ||= {}
+        (settings["hooks"][event] ||= []) << { "matcher" => "", "hooks" => [hook] }
+      end
+
+      def write(file, data)
+        FileUtils.mkdir_p(File.dirname(file))
+        File.write(file, JSON.pretty_generate(data))
+      end
+    end
+  end
+end

data/lib/maf/bootstrap/dependencies.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Maf
+  module Bootstrap
+    # Dependencies reports required and optional tools. It installs the
+    # required tools only when the options ask for it.
+    class Dependencies
+      def initialize(options)
+        @options = options
+      end
+
+      def report
+        REQUIRED_DEPS.each { |bin, meta| report_required(bin, meta) }
+        OPTIONAL_DEPS.each { |bin, hint| report_optional(bin, hint) }
+      end
+
+      private
+
+      def report_required(bin, meta)
+        return Bootstrap.say("#{bin}: present") if Bootstrap.which(bin)
+        return install(bin, meta) if @options.install_deps && !@options.check
+
+        Bootstrap.say("#{bin}: MISSING (required - #{meta[:why]}). Re-run with --install-deps or install it yourself.")
+      end
+
+      def install(bin, meta)
+        Bootstrap.say("#{bin}: missing -> installing (#{meta[:why]})")
+        meta[:install].call || abort("bootstrap: failed to install #{bin}")
+      end
+
+      def report_optional(bin, hint)
+        state = Bootstrap.which(bin) ? "present" : "missing (optional - #{hint})"
+        Bootstrap.say("#{bin}: #{state}")
+      end
+    end
+  end
+end

data/lib/maf/bootstrap/git_hook_planner.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Maf
+  module Bootstrap
+    # GitHookPlanner plans the git hooks: the commit guard, and the flow block
+    # in the post-commit and post-merge hooks.
+    class GitHookPlanner
+      COMMIT_GUARD = "git-hooks/pre-commit"
+      # Hook event name -> the asset source symbol that holds the block.
+      DOC_GRAPH_HOOKS = { "post-commit" => :post_commit, "post-merge" => :post_merge }.freeze
+
+      def initialize(project)
+        @project = project
+      end
+
+      # The commit guard blocks commits by roles with can_edit false. A foreign
+      # pre-commit hook stays, even with --force: it may run the project checks.
+      def commit_guard
+        dest = hook_path("pre-commit")
+        return [] unless dest
+
+        status = commit_guard_status(dest)
+        [@project.action(status, dest, @project.refuse_label(status, dest, FOREIGN_GUARD), COMMIT_GUARD)]
+      end
+
+      # Append the flow block to the post-commit and post-merge hooks. A foreign
+      # hook (graphify installs one) stays; the flow owns only its block.
+      def doc_graph_hooks
+        DOC_GRAPH_HOOKS.map { |name, source| hook(name, source) }
+      end
+
+      private
+
+      FOREIGN_GUARD = "a foreign pre-commit hook; the commit guard is off"
+
+      def commit_guard_status(dest)
+        return :create unless File.exist?(dest)
+        return :refuse unless @project.ours?(dest, COMMIT_GUARD_SIGNATURE)
+
+        @project.changed_script?(dest, COMMIT_GUARD) ? :update : :skip
+      end
+
+      def hook(name, source)
+        dest = hook_path(name)
+        return @project.action(:skip, "git hook #{name} (no git repository)") unless dest
+
+        @project.action(hook_status(dest, source), dest, dest, source)
+      end
+
+      def hook_status(dest, source) = File.exist?(dest) && block_current?(dest, source) ? :skip : :merge_hook
+
+      def block_current?(dest, source)
+        MarkedBlock.new(File.read(dest)).current?(@project.append_content(source))
+      end
+
+      def hook_path(name)
+        hooks = git_hooks_dir
+        hooks && File.join(hooks, name)
+      end
+
+      def git_hooks_dir
+        cmd = ["git", "-C", @project.target, "rev-parse", "--git-path", "hooks"]
+        path = IO.popen(cmd, err: File::NULL, &:read).strip
+        $?.success? && !path.empty? ? File.expand_path(path, @project.target) : nil
+      end
+    end
+  end
+end

data/lib/maf/bootstrap/global_taskrc_warning.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Maf
+  module Bootstrap
+    # GlobalTaskrcWarning warns when an older install left the UDA block in the
+    # user's global ~/.taskrc. Earlier versions of this installer shared one
+    # Taskwarrior database across every project. The warning stops old tasks
+    # from staying stranded there without notice.
+    class GlobalTaskrcWarning
+      def initialize(project)
+        @project = project
+      end
+
+      def run
+        return unless File.exist?(global) && File.read(global).include?(MARKER)
+        return if same_file?(global, @project.taskrc_path)
+
+        target = @project.target
+        puts format(MIGRATION_NOTE, taskrc: global, project: target, project_name: File.basename(target))
+      end
+
+      private
+
+      def global
+        ENV.fetch("TASKRC", File.join(Dir.home, ".taskrc"))
+      end
+
+      def same_file?(first, second)
+        File.exist?(first) && File.exist?(second) && File.identical?(first, second)
+      end
+    end
+  end
+end

data/lib/maf/bootstrap/graph_home.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Maf
+  module Bootstrap
+    # GraphHome moves the graph of an older install from .maf/graphify-out/ to
+    # graphify-out/ at the project root, and the vault from .maf/obsidian/ to
+    # graphify-out/obsidian/. The vault watcher writes the graph, so it stops
+    # first. VaultStarter starts it again after the move.
+    class GraphHome
+      OLD_GRAPH = File.join(MAF_DIR, "graphify-out")
+      OLD_VAULT = File.join(MAF_DIR, "obsidian")
+      VAULT = File.join(GRAPH_DIR, "obsidian")
+
+      def initialize(project) = @project = project
+
+      def move
+        return unless Dir.exist?(path(OLD_GRAPH)) || Dir.exist?(path(OLD_VAULT))
+
+        stop_watcher
+        graph_moves = movable?(OLD_GRAPH, GRAPH_DIR)
+        relocate(OLD_GRAPH, GRAPH_DIR) if graph_moves
+        move_vault(graph_moves)
+      end
+
+      private
+
+      # A graph at the root is newer than the old one, or belongs to the user. It stays.
+      def movable?(old, new) = Dir.exist?(path(old)) && !kept?(old, new)
+
+      # The moved graph folder can hold a stray vault that an agent exported.
+      # The old scripts deleted it before each export, so the real vault replaces it.
+      def move_vault(graph_moved)
+        return unless Dir.exist?(path(OLD_VAULT))
+
+        FileUtils.rm_rf(path(VAULT)) if graph_moved
+        relocate(OLD_VAULT, VAULT) unless kept?(OLD_VAULT, VAULT)
+      end
+
+      # True when NEW exists. The old folder then stays where it is.
+      def kept?(old, new)
+        return false unless File.exist?(path(new))
+
+        Bootstrap.say("keep   #{old} (#{new} exists)")
+        true
+      end
+
+      def relocate(old, new)
+        FileUtils.mkdir_p(File.dirname(path(new)))
+        FileUtils.mv(path(old), path(new))
+        Bootstrap.say("done   move #{old} -> #{new}")
+      end
+
+      def stop_watcher
+        script = @project.bin_path("vault")
+        pid = path(MAF_DIR, "coordination", "vault.pid")
+        system(script, "stop", chdir: @project.target, out: File::NULL) if File.exist?(pid) && File.exist?(script)
+      end
+
+      def path(*parts) = @project.path(*parts)
+    end
+  end
+end

data/lib/maf/bootstrap/hook_merger.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Maf
+  module Bootstrap
+    # HookMerger puts the flow block at the top of a git hook. The rest of the
+    # hook stays. A hook in another language than sh stays as it is.
+    class HookMerger
+      SH_SHEBANG = %r{\A#!\s*(?:/usr/bin/env\s+)?(?:\S*/)?(?:ba)?sh(?:\s|\z)}
+
+      def initialize(project)
+        @project = project
+      end
+
+      # Returns true when the hook changed.
+      def merge(file, source)
+        return skip_foreign_hook(file) if foreign_interpreter?(file)
+
+        body = File.exist?(file) ? MarkedBlock.new(File.read(file)).remove : "#!/bin/sh\n"
+        write_hook(file, prepend_block(body, @project.append_content(source)))
+      end
+
+      private
+
+      def foreign_interpreter?(file)
+        return false unless File.exist?(file)
+
+        first = File.open(file, &:gets).to_s
+        first.start_with?("#!") && !first.match?(SH_SHEBANG)
+      end
+
+      def skip_foreign_hook(file)
+        Bootstrap.say("skip   #{file}: foreign hook with a non-sh shebang, doc-graph refresh is off")
+        false
+      end
+
+      def prepend_block(body, block)
+        shebang, rest = split_shebang(body)
+        "#{shebang}#{block.chomp}\n#{rest.lstrip}"
+      end
+
+      def split_shebang(body)
+        first, *rest = body.lines
+        first&.start_with?("#!") ? [first, rest.join] : ["", body]
+      end
+
+      def write_hook(file, text)
+        File.write(file, text)
+        FileUtils.chmod("+x", file)
+        true
+      end
+    end
+  end
+end