maf 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4cdbedeaf3c68e4b2aa40939c8f006f846d0d044531f2c6d53e01cddf4d9e45d
+  data.tar.gz: e90a24b66c78fd7cc493e493f722b25a5803430967b2cae0de46202befaf12b2
+SHA512:
+  metadata.gz: ee79aa5c928c7be62ed39cdcf2904f7905b6e33189c31f19b7badd522cd0600431d6b39faebf72c7f60caf951ddbb577efc6d2a1fc167145f4f2503665ffe256
+  data.tar.gz: 0aa9875967605035e251dab51a6ad097dc80c428cda40a8db8abfad99d0cb5381d92da1c5b7e9dc5b4daa5d7263e670655150100a40f70fb0ec9369b35f868fe

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-08
+
+- First release as a gem: `gem install maf`.
+- All code is in the `Maf` module.
+- The command moved from `bin/maf` to `exe/maf`. `bin/maf` stays for the links
+  that point to it. A later version removes it.
+- New commands: `maf version` and `maf guide` (prints the agent setup guide).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dominik Alberski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,411 @@
+# multi_agent_flow
+
+Coordination layer for running several AI coding agents (opencode, Claude Code,
+Hermes, Codex) in parallel on one repository, each in its own terminal.
+
+Three pillars:
+
+| Pillar | Implementation |
+|---|---|
+| Communication | Taskwarrior task board + `.maf/coordination/` inbox, via the `coord` CLI |
+| Resource control | `mkdir`-based locks — no `flock`, works on macOS and Linux |
+| Shared memory | graphify knowledge graph + Obsidian vault, served over MCP |
+
+The whole layer is **CLI + files**: every harness uses it identically; no GUI or
+vendor dependency.
+
+---
+
+## Requirements
+
+The `maf` gem holds the flow. Install these tools yourself:
+
+| Tool | Why | Install |
+|---|---|---|
+| Ruby 3.0+ | runs `maf`, `coord`, and the other scripts | macOS: `brew install mise && mise install ruby`. Linux: your package manager or [mise](https://mise.jdx.dev) |
+| git | worktrees, hooks, the local exclude file | macOS: `xcode-select --install` or `brew install git`. Linux: `apt install git` |
+| Taskwarrior | the task board | macOS: `brew install task`. Linux: `apt install taskwarrior` |
+| One or more harnesses | the agents | [Claude Code](https://docs.claude.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [opencode](https://opencode.ai), [Hermes](https://github.com/NousResearch/hermes-agent) |
+| graphify (optional) | the shared knowledge graph | `uv tool install graphifyy` |
+
+Install the gem:
+
+```sh
+gem install maf
+maf version
+```
+
+Upgrade the gem. Then run `maf update` in each project: it replaces the flow files with the new versions.
+
+```sh
+gem update maf
+cd ~/Projects/my-app && maf update
+```
+
+## Fast path — agent-driven
+
+1. Install the gem: `gem install maf`.
+2. Open any AI coding agent in your project folder and say:
+
+   > Run `maf guide`. Read the output and implement it.
+
+The agent asks which harnesses and roles to use, runs `maf add`, and prints
+the `maf start` commands to start each session.
+
+`maf guide` prints **[install.md](install.md)**: the exact instructions that the agent follows.
+
+## Manual path - the maf command
+
+Run `maf` in the project root.
+
+```sh
+cd ~/Projects/my-app
+maf roles                                             # list the roles
+maf add claude:architect opencode:backend-developer   # install the flow and add agents
+maf start claude architect                            # start one agent in its worktree
+maf help                                              # all commands
+```
+
+Run `maf` without a command to use the interactive menu. The menu asks for
+each value: harness, roles, models, and the agent to start.
+
+---
+
+## Project layout
+
+The flow keeps every file that it owns in one folder, `.maf/`, in the project.
+The knowledge graph is the exception: it is project knowledge, not tooling, so it
+lives in `graphify-out/` at the project root, where graphify looks by default.
+
+```
+.maf/
+  bin/            coord, dispatcher, vault, dashboard, analyst, doc-graph-refresh
+  lib/maf/shared/ code that the scripts in bin/ load (maf update replaces it)
+  coordination/   task board, inbox, locks, presence, sessions, hooks, logs
+  worktrees/      one git worktree per worker
+  agents/         role files: claude/, opencode/, codex/
+  claude/         settings.json: the Claude Code hooks (maf start passes --settings)
+  mcp/            the graphify MCP server for Claude Code and opencode
+  config.json     the agents and settings of the project
+  roles.yml       project roles (you write it; maf role add NAME)
+  workflow.md     stage instructions for the architect (you write it)
+  env.sh          source it: puts .maf/bin on PATH
+graphify-out/     knowledge graph (excluded from git; each worktree has a symlink to it)
+  memory/         work memory notes: a worktree of the orphan branch maf/memory (ADR 0006)
+  obsidian/       generated Obsidian vault
+```
+
+maf is a tool, not a part of the project. Nothing that runs maf goes into git:
+`.maf/` and each link and plugin that maf creates are listed in `.git/info/exclude`,
+which is local to the clone. maf never edits a file that the project tracks.
+
+The project keeps what the agents make, also after `maf uninstall`:
+
+| Path | What it is |
+|---|---|
+| the code | The work of the agents, landed on the goal branches. |
+| `GLOSSARY.md` | The domain glossary. The project manager drafts it. A worker commits it on the architect's task. |
+| `docs/decisions/` | ADRs. The architect decides them. A worker commits them. |
+
+Local files that a harness or git reads outside `.maf/`:
+
+| Path | Reason |
+|---|---|
+| `.git/hooks/*` | Git reads them there. |
+| `.git/info/exclude` | Keeps the flow out of git in this clone. |
+| `.claude/agents/`, `.opencode/agents/`, `.codex/prompts/` | Symlinks into `.maf/agents/<harness>/`. |
+| `.opencode/plugins/board-watch.js` | opencode reads it there. |
+| `.codex/hooks.json` | Codex reads it there. Excluded when the project does not track it. |
+| `~/.hermes/skills/<project>-<role>/SKILL.md` | Hermes reads it there. |
+
+Claude Code gets the hooks from `.maf/claude/settings.json` (`--settings`) and the
+graphify MCP server from `.maf/mcp/claude.json` (`--mcp-config`). opencode gets the
+server from `.maf/mcp/opencode.json` (`OPENCODE_CONFIG`). `maf start` and the
+dispatcher pass these files. The project's `.claude/settings.json`, `.mcp.json`,
+`opencode.json`, `AGENTS.md`, and `CLAUDE.md` stay as they are.
+
+MAF installs Codex hooks in the project `.codex/hooks.json` file.
+Hooks act only on sessions that `maf start` registers.
+Each hook checks the launch token, process, worktree, role, worker, board, and harness session ID.
+An independent session does not activate hooks, even with inherited coordination variables.
+`maf update` disables the legacy global Codex hook and removes only its registration.
+Other global hooks stay.
+Restart workers with `maf start` after the update.
+
+A project with the old layout runs `maf migrate` once. See the migration
+section of [USER_MANUAL.md](USER_MANUAL.md).
+
+---
+
+## Documentation
+
+| File | Audience | What it covers |
+|---|---|---|
+| **[docs/flow-glossary.md](docs/flow-glossary.md)** | Everyone | Flow terms: harness, role, worker, agent, task, message, claim, lock, hooks. [docs/flow-cli-names.md](docs/flow-cli-names.md) lists their names in code and CLI |
+| **[GETTING_STARTED.md](GETTING_STARTED.md)** | First-time user | Concepts, prerequisites, manual install, basic workflow |
+| **[USER_MANUAL.md](USER_MANUAL.md)** | Setting up a real team | Full install (maf), all harnesses, dispatcher, monitoring |
+| **[install.md](install.md)** | An AI coding agent | Interactive wizard: asks the user for harnesses/roles, runs `maf add` |
+| **[docs/out-of-scope.md](docs/out-of-scope.md)** | Contributor | Requests that the project rejects on purpose, with the reason |
+| **[SKILL.md](SKILL.md)** | Agent skill loader | Self-contained portable skill (frontmatter + full API reference) |
+
+---
+
+## Contents
+
+```
+multi_agent_flow/
+  install.md                  # agent instruction: interactive setup wizard
+  SKILL.md                    # portable skill for agent skill loaders
+  README.md                   # this file
+  docs/flow-glossary.md       # flow terms
+  docs/flow-cli-names.md      # code and CLI name of each flow term
+  GETTING_STARTED.md          # first-time walkthrough (concepts + manual setup)
+  USER_MANUAL.md              # full team setup reference
+  maf.gemspec                 # the gem: files, version, the webrick dependency
+  Gemfile                     # development gems: rake, minitest, rubocop
+  CHANGELOG.md                # changes per version
+  exe/
+    maf                       # the maf command line tool (gem install maf puts it on PATH)
+  bin/
+    maf                       # old path of the command; loads exe/maf
+    setup                     # bundle install
+    console                   # irb with maf loaded
+  lib/maf.rb                  # require "maf" loads the command line tool
+  lib/maf/
+    version.rb                # Maf::VERSION
+    cli.rb                    # maf subcommands
+    menu.rb                   # interactive menu (maf without a command)
+    prompt.rb                 # numbered terminal questions for the menu
+    flow.rb                   # generates harness-specific role files + installs coordination layer
+    bootstrap.rb              # idempotent coordination layer installer
+    setup_agent.rb            # maf start: worktree + harness launch
+    uninstall.rb              # removes the flow from a project; keeps graphify-out/
+    migrate.rb                # maf migrate: moves an old-layout install into .maf/
+    team.rb                   # maf prepare: adds or replaces one worker
+    team_command.rb           # maf team: shows the team, or sets its budget
+    retire.rb                 # maf retire: removes one worker and archives its state
+    worker_control.rb         # maf worker: stops, starts, or restarts one worker
+    flow/role_catalog.rb      # merges .maf/roles.yml over the built-in roles
+    flow/workflow.rb          # reads .maf/workflow.md for the architect prompt
+    flow/mcp_config.rb        # writes the graphify MCP server into .maf/mcp/
+    untrack.rb                # maf untrack: removes an older install from git
+    local_exclude.rb          # the flow block in .git/info/exclude
+    shared/                   # stdlib-only code that the maf CLI and the scripts share (installed as .maf/lib/maf/shared/)
+  scripts/
+    check.rb                  # repo consistency check (UDA sync, markers, script signatures)
+  templates/
+    roles.yml                 # role definitions + model hints
+    role-stub.yml.erb         # stub that maf role add writes
+    workflows/                # default workflows: simple, plan-review, tdd, panel
+    opencode.md.erb           # role file templates per harness
+    claude.md.erb
+    codex.md.erb
+    hermes.md.erb
+  assets/
+    coord                     # coordination CLI (Ruby)
+    dispatcher                # polls task board + inbox, starts one-shot agents (Ruby)
+    vault                     # graphify + Obsidian + MCP watcher control, graph age (Ruby)
+    dashboard                 # web dashboard: workers table with actions, alerts, board (Ruby/WEBrick)
+    analyst                   # asks a small model for token hints about one worker (dashboard analyze button)
+    doc-graph-refresh         # graphify rebuild runner called by the git hooks (Ruby)
+    env.sh                    # shell environment: .maf/bin on PATH (installed as .maf/env.sh)
+    git-hooks/                # pre-commit guard, post-commit/post-merge refresh blocks
+    taskrc.append             # Taskwarrior UDA block
+    agents-contract.md        # coordination contract at the end of each role prompt
+    harness-hooks/            # next-task, board-watch, session-guard, and context-watch scripts, and the opencode plugin
+  test/
+    coord_test.rb             # behavioral tests for the coord CLI
+    installer_test.rb         # tests for bootstrap.rb, flow.rb, setup_agent.rb
+    maf_test.rb               # tests for the maf command
+    dashboard_test.rb         # tests for the dashboard data
+    dispatcher_test.rb        # tests for the dispatcher
+    uninstaller_test.rb       # tests for uninstall.rb
+    migrate_test.rb           # tests for migrate.rb
+    roles_workflow_test.rb    # tests for project roles and the workflow
+    graph_age_test.rb         # tests for vault age and the graph prompt rules
+    mcp_test.rb               # tests for the MCP server wiring
+    doc_graph_refresh_test.rb # tests for the doc-graph refresh script
+    board_watch_test.rb       # tests for the board watcher
+    context_watch_test.rb     # tests for the context-watch hook
+    hook_session_test.rb      # tests for session isolation
+    hook_config_test.rb       # tests for project hooks
+    worker_control_test.rb    # tests for maf worker
+    untrack_test.rb           # tests for maf untrack
+    analyst_test.rb           # tests for the analyst
+    shared_test.rb            # tests for lib/maf/shared/
+    gemspec_test.rb           # tests that the gem holds every runtime file
+```
+
+---
+
+## Use as a skill
+
+Copy or symlink this directory into a skills location so agents can discover it.
+The skill loader matches the folder name to `name:` in the frontmatter; the
+installed folder must be `multi-agent-flow` (hyphen, not underscore):
+
+```sh
+cp -R "$PWD" ~/.config/opencode/skills/multi-agent-flow
+# or, for Claude Code:
+cp -R "$PWD" ~/.claude/skills/multi-agent-flow
+```
+
+The skill runs the `maf` command. Install the gem first: `gem install maf`.
+Restart the agent to load the skill. You can also hand `SKILL.md` plus `assets/`
+to any agent as direct context.
+
+---
+
+## Doc-graph refresh
+
+A commit or merge that changes a markdown file refreshes the shared knowledge
+graph. `maf add` appends a flow block to the `post-commit` and `post-merge`
+hooks. The block starts `.maf/bin/doc-graph-refresh` detached, so the commit
+returns at once.
+
+The refresh runs `graphify extract . --backend gemini` and then
+`graphify export obsidian --dir graphify-out/obsidian`. The graph lives in `graphify-out/`
+at the project root. It builds in a temp dir and swaps the derived files on
+success, so a failed extract keeps the old graph. The swap never replaces
+`graphify-out/memory/` or `graphify-out/obsidian/`. It then runs `graphify reflect` on the
+saved notes. It needs `GEMINI_API_KEY`.
+Without the key it logs a skip in `.maf/coordination/doc-graph.log` and exits. A
+non-markdown commit makes no LLM call. A refresh started in a worktree writes
+the shared graph in the main checkout.
+
+---
+
+## Contributor reference
+
+After editing the UDA block or the worktree-path formula:
+
+```sh
+ruby scripts/check.rb
+```
+
+Verifies: the UDA block in `assets/coord` matches `assets/taskrc.append`; the
+markers are present; the worktree path formula is identical in `assets/coord`
+and `lib/maf/setup_agent/worktree.rb`; each script carries its signature; and the
+literals that the standalone scripts share (lead roles, read-only toolsets,
+the report format, the presence start time) are identical.
+
+Install the development gems once:
+
+```sh
+bin/setup                          # bundle install
+```
+
+Run the checks and all tests:
+
+```sh
+bundle exec rake                               # scripts/check.rb, RuboCop, then all tests
+bundle exec rake lint              # RuboCop only
+bundle exec rake test TEST=test/coord_test.rb  # one test file
+```
+
+To use maf from the clone, link `exe/maf` into a folder on `PATH`:
+
+```sh
+ln -sf "$PWD/exe/maf" ~/.local/bin/maf
+```
+
+Build and install the gem from the clone:
+
+```sh
+bundle exec rake build             # writes pkg/maf-VERSION.gem
+bundle exec rake install           # builds and installs the gem
+```
+
+To release, change `Maf::VERSION` in `lib/maf/version.rb` and add a
+`CHANGELOG.md` entry.
+
+RuboCop (pinned in the `Gemfile`) uses `.rubocop.yml`. It sets the
+size rules: a class at most 100 lines, a method at most 5 lines and 4
+parameters, a line at most 120 characters. `.rubocop_todo.yml` lists the code
+that broke a rule before the config existed. Fix an entry, then delete it.
+Do not add new entries.
+
+`rake test` runs each test file in its own process, in parallel, and prints the
+output of a failed file only. It unsets the variables below for each test.
+
+An agent session exports `TASKRC` and `COORD_DIR` for the shared board. Unset
+them when you run a test file directly, so a test never writes to that board:
+
+```sh
+env -u TASKRC -u COORD_DIR -u COORD_ROLE -u COORD_WORKER ruby test/coord_test.rb
+```
+
+```sh
+ruby test/coord_test.rb      # covers the coord CLI
+ruby test/installer_test.rb  # covers bootstrap.rb, flow.rb, setup_agent.rb
+ruby test/uninstaller_test.rb  # covers uninstall.rb
+ruby test/migrate_test.rb    # covers migrate.rb
+ruby test/roles_workflow_test.rb  # covers project roles and the workflow
+ruby test/graph_age_test.rb  # covers vault age and the graph prompt rules
+ruby test/mcp_test.rb        # covers the MCP server wiring
+ruby test/maf_test.rb        # covers the maf command
+ruby test/dashboard_test.rb  # covers the dashboard data
+ruby test/doc_graph_refresh_test.rb  # covers the doc-graph refresh
+ruby test/hook_session_test.rb       # covers session isolation
+ruby test/hook_config_test.rb        # covers project hooks and legacy hook removal
+ruby test/dispatcher_test.rb         # covers the dispatcher
+ruby test/board_watch_test.rb        # covers the board watcher
+ruby test/context_watch_test.rb      # covers the context-watch hook
+ruby test/worker_control_test.rb     # covers maf worker
+ruby test/untrack_test.rb            # covers maf untrack
+ruby test/analyst_test.rb            # covers the analyst
+ruby test/shared_test.rb             # covers lib/maf/shared/
+```
+
+Minitest, stdlib only. Tests that require `task`, `git`, or `node` skip (exit 0)
+when those tools are absent. The dashboard tests need the `webrick` gem.
+CI (`.github/workflows/test.yml`) installs all of them and runs the checks and
+tests on Linux and macOS, and RuboCop, for each push to `main` and each pull
+request.
+
+---
+
+## Design notes
+
+- **Taskwarrior is the single source of truth**, in a project-local database
+  (`.maf/coordination/taskdata`, via `.maf/coordination/taskrc`) — never the user's
+  global `~/.task`. Two projects on this flow never share one board.
+  `coord board`/`export` are read-only projections.
+- **Agents never call `task` directly.** `coord` keeps the protocol stable and
+  lets the storage backend change later.
+- **Terminology:** see [docs/flow-glossary.md](docs/flow-glossary.md). One role can run as several
+  workers. `claim` is atomic, so two workers cannot take the same task.
+- **A claim is a lease.** Idle past `COORD_LEASE_TTL` seconds (default 4 hours)
+  it becomes claimable again without `--force`. `coord unclaim` releases one on
+  demand.
+- **Worktrees live inside the project** at `.maf/worktrees/<role>-<worker_id>`.
+  `.maf/worktrees/` is excluded from git. In each worktree, run `source .maf/env.sh` so
+  `COORD_DIR` and `TASKRC` point at the main project; every worktree shares one
+  `.maf/coordination/` dir and one task board.
+- **Scope overlap** is checked on `coord add` (warning) and `coord conflicts`
+  (report). It is a path-prefix heuristic, not a full glob matcher. Scope is
+  advisory: nothing but agent discipline stops a write outside it, except that
+  roles with `can_edit: false` get a restricted tool grant where the harness
+  supports one (Claude Code, opencode, Hermes), and the git `pre-commit` guard
+  refuses their commits.
+- **The `ollama` lock** is required when one local model host serves several
+  agents. Exclusion is TTL-based: coord stores no pid. A lock is reclaimed once its
+  TTL elapses (default 3600s), even if the holder is still alive. A killed
+  holder keeps the lock until the TTL elapses.
+- **The `project-manager` role** is the user's proxy: the user talks to it, it
+  creates goals (`coord goal add`), sends them to the architect, and relays the report back. Without
+  `project-manager`, the user talks to the architect directly.
+- **Rejected requests are logged.** When you reject a request on purpose, add
+  an entry to [docs/out-of-scope.md](docs/out-of-scope.md): the request, the
+  date, the source, and the reason. Read the log before you propose a feature.
+- **UI is deliberately deferred**: Obsidian (Kanban/Dataview) or
+  `taskwarrior-tui` can read the same data without any agent changes.
+
+---
+
+## Acknowledgements
+
+- The `panel` workflow and the `skeptic` and `auditor` roles come from
+  [shipyard](https://github.com/esse/shipyard) by Piotr Szmielew. Shipyard sends
+  a plan and a branch to adversarial reviewers from different model families.
+  The rules for critical findings and cited lines also come from shipyard.

data/assets/agents-contract.md

@@ -0,0 +1,80 @@
+<!-- >>> multi-agent-flow >>> -->
+## Multi-agent coordination
+
+This project uses `coord`, a shared task board for several coding agents.
+Run `source .maf/env.sh` once. It puts `coord` on `PATH` and points `COORD_DIR` at the shared board.
+Use `coord`. Never use raw `task`.
+Your role file holds your work loop. This section holds the terms and rules that all roles share.
+
+### Terms
+
+- A role is a project function, for example `backend-developer`. A task belongs to a role.
+- A worker is one instance of a role, for example `backend-1`. `COORD_ROLE` and `COORD_WORKER` identify you.
+- A goal is one user-visible outcome. A goal has the branch `goal/<short-id>`.
+- A task is one part of a goal. A worker does the task on the branch `task/<short-id>`.
+- The lead roles are the project manager and the architect. A lead role never claims a task and never commits.
+- Use the terms of the project glossary, `GLOSSARY.md` at the repository root.
+
+### Hierarchy
+
+If the project has a project manager, the user talks only to the project manager.
+The project manager sends each goal to the architect.
+The architect splits the goal into tasks, lands the done tasks, and reports back.
+Workers never talk to the user. Workers ask the architect with `coord msg`.
+
+### Commands
+
+```
+coord show ID                                # one task: its fields and annotations (the task spec)
+coord next [ROLE] [--wait] | --mine          # unclaimed tasks, or your claimed tasks
+coord claim ID | start-task ID | done ID     # take a task, check out its branch, finish it
+coord annotate ID TEXT                       # add a note to a task
+coord lesson ID dead_end|corrected TEXT      # an approach that failed, or the right way: the graph keeps it
+coord escalate [--task ID] TEXT              # a problem you cannot fix: the project manager asks the user
+coord msg --from A [--task ID] [--fyi] TO TEXT   # message a role or a worker; --task also notes the task
+                                             # --fyi: no run starts; the next run of TO reads it
+coord broadcast --from A [--to workers|leads|all] TEXT
+coord inbox [ROLE] [--wait]                  # read your messages
+coord await                                  # interactive Codex: arm the stop hook, then end your turn
+coord goal list | goal show ID               # open goals, or one goal and its tasks
+coord who | status | log [N]                 # live workers, tasks by role, recent events
+coord with-lock NAME -- CMD                  # run a command under a lock
+```
+
+If a dispatcher serves your role, the prompt holds your messages. Do not run `coord inbox` then.
+
+A worker has no inbox of its own. A message for a worker goes to the inbox of its role.
+Any worker of the role can read it. The `for:` line names the worker.
+If a message is about a task, send it with `--task ID`. The text then also stays as a note on the task.
+If a message names a task that you do not hold, run `coord show ID` before you act.
+
+### Rules
+
+1. One writer per path. The task scope lists the paths that you own. Never edit outside the scope.
+2. A role with `can_edit: false` cannot commit. The git `pre-commit` hook refuses the commit.
+3. Run each local model generation under the `ollama` lock: `coord with-lock ollama -- <command>`.
+4. Run each command that needs a shared resource (browser, system tests, one fixed port) under one lock:
+   `coord with-lock system-test -- <command>`. Do not invent other lock names.
+5. Each worktree has its own test database and server port. Do not share a test database.
+
+### Tests
+
+- Task tests: the unit tests and the tests for the changed behavior. The worker runs them before the report.
+- Merge suite: the full suite, with system tests. Only the architect runs it, one time per goal.
+- The reviewer does not run tests. The reviewer reads the TESTS line of the report.
+
+### Handoff artifacts
+
+- A shared working file is an artifact. Write it to `$COORD_DIR/artifacts/<goal>/<name>.md`.
+  Run `mkdir -p` for the folder first.
+- Never write an artifact inside a worktree. Worktrees do not share files.
+- A worker commits each durable artifact (an approved spec, an ADR) on the goal branch.
+
+### Domain documentation
+
+- `GLOSSARY.md` holds domain terms only. The file does not exist until the first term resolves.
+- Each term has a bold name, one or two sentences, and an optional `_Avoid_` line for rejected words.
+- The decisions folder holds the ADRs: `.agent/decisions/` if it exists, else `docs/decisions/`.
+  Append. Never rewrite an ADR.
+- `graphify-out/obsidian/` is rebuilt from the code graph. Do not keep permanent notes there.
+<!-- <<< multi-agent-flow <<< -->