modus-operandi 0.1.0__py3-none-any.whl

modus_operandi/__init__.py

@@ -0,0 +1,24 @@
+"""modus-operandi package: the launcher and the install/bootstrap flow.
+
+The package carries the pipeline artifacts as package data under
+``data/`` (pipeline scripts, prompts, workflows, the config example and the
+victory sound) and renders them into the user config base on first run
+(``modus_operandi.cli.ensure_installed``). ``__version__`` is mirrored in
+``pyproject.toml``; both are bumped together on release.
+"""
+
+from .paths import Paths
+
+# The package's public surface: the install layout type and the
+# user-facing install failure. (The explicit __all__ marks Paths as a
+# re-export of the paths.py alias; InstallError and __version__ are
+# defined in this module.)
+__all__ = ["InstallError", "Paths", "__version__"]
+
+__version__ = "0.1.0"
+
+
+class InstallError(Exception):
+    """User-facing failure of the install/bootstrap flow."""
+
+    pass

modus_operandi/bootstrap.py

@@ -0,0 +1,52 @@
+"""Bootstrap: materialize the rendered installation on first run / update.
+
+One responsibility: check the ``install-version.txt`` marker against the
+package ``__version__`` and, when the rendered artifacts are missing or
+stale, render them from the package data (prerequisites check + apply) and
+report one status line. The launcher (cli.py) owns the argument parsing and
+dispatch; this module owns the installation state — it changes together with
+installer/verify, not with the command surface.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from . import InstallError, Paths, __version__, installer, verify
+
+
+def ensure_installed(layout: Paths, check_prereqs: bool = True) -> int:
+    """Bootstrap the rendered installation from the package data.
+
+    Reads ``install-version.txt`` (config base /modus-operandi/install-version.txt):
+    when the file is missing or its version differs from the package
+    ``__version__``, checks the prerequisites and renders every artifact from
+    the package data (``apply()`` records the marker), then prints exactly
+    one status line. Returns 0 on success (including an up-to-date
+    installation) and 1 on error, with the reason on stderr.
+
+    ``check_prereqs=False`` skips the tool-presence checks: the `edit` flow
+    never runs the backend CLI, so a user who uninstalled it (or switched
+    configs) must still be able to edit the config and re-render the
+    artifacts.
+    """
+    marker = layout["install_version"]
+    if marker.exists() and marker.read_text(encoding="utf-8").strip() == __version__:
+        return 0
+    was_installed = marker.exists()
+    if check_prereqs:
+        try:
+            verify.check_prerequisites(layout)
+        except InstallError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+    try:
+        installer.apply(layout)
+    except (InstallError, OSError, ValueError, KeyError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    if was_installed:
+        print(f"modus-operandi: updated to {__version__}", flush=True)
+    else:
+        print(f"modus-operandi: installed to {layout['config_dir']}", flush=True)
+    return 0

modus_operandi/cli.py

@@ -0,0 +1,313 @@
+#!/usr/bin/env python3
+"""modus-operandi - global launcher for the modus-operandi pipelines (console-script entry).
+
+Installed by pip as the ``modus-operandi`` console script and callable from any
+project directory, without `specify init` required. It delegates to the
+installed run-pipeline.py wrapper with the absolute workflow path, so runs
+keep the timestamps, live step output, run statistics and the victory sound.
+`modus-operandi edit` opens the installed config.yml in your terminal editor and
+applies it on save and close — a valid config is applied, an invalid one is
+rolled back, an unchanged one is left as-is. `modus-operandi uninstall` removes
+the rendered pipeline files from the machine.
+
+The launcher resolves every installed path at runtime: run-pipeline.py, both
+workflows and config.yml come from the config base directory derived from
+XDG_CONFIG_HOME/$HOME. Nothing is baked into this file at install time.
+Before dispatching a task/review/edit run, the launcher bootstraps the
+installation (ensure_installed): when the rendered artifacts are missing or
+stale, it renders them from the package data and prints one status line.
+
+This module is the entry point of a module split, one concern per file: the
+`edit` execution flow lives in edit_command.py, the shared editor resolution
+in editor.py (the same editor.py the run-pipeline wrapper uses for its
+feedback gate), the exceptions package ships one class per file, the
+bootstrap (first-run/update render) lives in bootstrap.py and the
+`uninstall` flow in uninstall.py.
+
+Usage:
+  modus-operandi task "task description" [-i key=value ...]
+  modus-operandi review [--branch-diff]
+  modus-operandi edit
+  modus-operandi uninstall [--yes]
+  modus-operandi --backend cursor task "task description"   # override the backend for this run
+  modus-operandi --help | -h
+
+Examples:
+  modus-operandi task "add a dark mode toggle"
+  modus-operandi task "add a dark mode toggle" -i task_id=dark-mode
+  modus-operandi --backend cursor task "add a dark mode toggle"
+  modus-operandi review
+  modus-operandi review --branch-diff
+  modus-operandi edit
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from modus_operandi import bootstrap, paths, uninstall
+from modus_operandi.edit_command import _run_edit
+from modus_operandi.editor import resolve_editor
+from modus_operandi.exceptions import (
+    EditRequested,
+    HelpRequested,
+    InvalidInvocation,
+    UninstallRequested,
+)
+
+# Public surface of the launcher: the pure mapping, the shared editor
+# resolution and the signals, so tests and callers keep a single import
+# target (the modus_operandi.cli module).
+__all__ = [
+    "CONFIG",
+    "REVIEW_WORKFLOW",
+    "RUN_PIPELINE",
+    "TASK_WORKFLOW",
+    "USAGE",
+    "build_command",
+    "print_usage",
+    "resolve_editor",
+]
+
+
+def _config_base() -> Path:
+    """The config root the installer writes into (XDG_CONFIG_HOME or ~/.config)."""
+    return Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
+
+
+def _scripts_dir() -> Path:
+    return _config_base() / "opencode" / "scripts"
+
+
+def _config_dir() -> Path:
+    return _config_base() / "modus-operandi"
+
+
+# Paths of the installed pipeline, derived from the config base at runtime
+# (XDG_CONFIG_HOME or ~/.config), so nothing is baked at install time.
+_LAYOUT = paths.build_paths_from_config_base(_config_base())
+RUN_PIPELINE = str(_scripts_dir() / "run-pipeline.py")
+REVIEW_WORKFLOW = str(_config_dir() / "review-pipeline.yml")
+TASK_WORKFLOW = str(_config_dir() / "task-pipeline.yml")
+CONFIG = str(_config_dir() / "config.yml")
+
+USAGE = """Usage: modus-operandi <subcommand> [args]
+
+  modus-operandi --backend <opencode|cursor> <subcommand> [args]
+      Override the configured backend for this run (the flag must precede
+      the subcommand; the config `backend:` remains the default).
+
+  modus-operandi task "task description" [-i key=value ...]
+      Run the full task pipeline for the task (motivation study -> research ->
+      ADR -> implementation -> review). All non-flag arguments after `task`
+      are joined into the task input; -i key=value arguments are passed
+      through to the workflow.
+
+  modus-operandi review [--branch-diff] [-i key=value ...]
+      Review the project code (default: the whole codebase). With --branch-diff
+      only the changes between the current branch and the default branch.
+
+  modus-operandi edit
+      Open the installed config.yml in your terminal editor (VISUAL, then
+      EDITOR, then nano, then vi). On save and close it validates the file:
+      a valid config is applied, an invalid one is rolled back, and one that
+      was left unchanged is not re-applied.
+
+  modus-operandi uninstall [--yes]
+      Remove the rendered pipeline files (~/.config/modus-operandi and the
+      modus-operandi files under ~/.config/opencode), then run
+      `pip uninstall modus-operandi` to remove the package itself. Asks for
+      confirmation unless --yes is given.
+
+  modus-operandi --help | -h
+      Print this help and exit 0.
+
+Examples:
+  modus-operandi task "add a dark mode toggle"
+  modus-operandi task "add a dark mode toggle" -i task_id=dark-mode
+  modus-operandi --backend cursor task "add a dark mode toggle"
+  modus-operandi review
+  modus-operandi review --branch-diff
+  modus-operandi edit
+"""
+
+
+def build_command(argv: list[str]) -> list[str]:
+    """Map modus-operandi argv to the command to execute (pure dispatch).
+
+    Raises HelpRequested for `--help`/`-h`, EditRequested for `edit`,
+    UninstallRequested for `uninstall` (carrying the `--yes` flag) and
+    InvalidInvocation for an unusable invocation; it never prints anything,
+    so mapping stays separate from presentation. The caller owns the usage
+    output and the exit code. A leading global `--backend <opencode|cursor>`
+    flag (before the subcommand) is consumed and forwarded to
+    run-pipeline.py.
+    """
+    if not argv:
+        raise InvalidInvocation
+    backend: str | None = None
+    head, rest = argv[0], argv[1:]
+    if head == "--backend":
+        if not rest:
+            raise InvalidInvocation
+        backend = rest[0]
+        if backend not in ("opencode", "cursor"):
+            raise InvalidInvocation
+        rest = rest[1:]
+        if not rest:
+            raise InvalidInvocation
+        head, rest = rest[0], rest[1:]
+    if head in ("-h", "--help"):
+        raise HelpRequested
+    if head == "task":
+        return _build_task_command(rest, backend)
+    if head == "review":
+        return _build_review_command(rest, backend)
+    if head == "edit":
+        # `edit` takes no arguments: anything after the subcommand is ignored.
+        # Editor resolution is environment-dependent (os.environ, shutil.which)
+        # and belongs to the edit execution path (edit_command._run_edit), not
+        # to this pure mapping; a signal keeps the subcommand ->
+        # execution-path decision in one place.
+        raise EditRequested
+    if head == "uninstall":
+        # `--yes` skips the confirmation prompt of the uninstall flow; extra
+        # arguments are ignored like for `edit`.
+        raise UninstallRequested("--yes" in rest)
+    raise InvalidInvocation
+
+
+def _build_text_input_command(
+    rest: list[str], backend: str | None, workflow: str, input_key: str
+) -> list[str]:
+    """Map the text-input subcommands (task) to a run-pipeline command.
+
+    The non-flag arguments are joined into a single text input
+    (`-i <input_key>=<joined text>`), while `-i key=value` pairs (the two
+    argv elements `-i` and `key=value`) and the combined single element
+    `"-i key=value"` are passed through to the workflow unchanged. A
+    dangling `-i` without a value is an invalid
+    invocation, not a flag to forward: specify would fail with a confusing
+    parser error, while other bad calls get a clear usage. The space in the
+    `-i ` prefix is required so text like `-integration` is not mistaken for
+    an input.
+    """
+    cmd = [RUN_PIPELINE]
+    if backend:
+        cmd += ["--backend", backend]
+    cmd.append(workflow)
+    text_parts: list[str] = []
+    passed: list[str] = []
+    i = 0
+    while i < len(rest):
+        arg = rest[i]
+        if arg == "-i":
+            if i + 1 >= len(rest):
+                # A dangling `-i` without a value is an invalid invocation,
+                # not a flag to forward: specify would fail with a confusing
+                # parser error, while other bad calls get a clear usage.
+                raise InvalidInvocation
+            # Shell-style pair: `-i key=value` as two argv elements.
+            passed.append(arg)
+            passed.append(rest[i + 1])
+            i += 2
+            continue
+        if arg.startswith("-i "):
+            # Combined single element: `-i key=value`. The space is required
+            # so text like `-integration` is not mistaken for an input.
+            passed.append(arg)
+        else:
+            text_parts.append(arg)
+        i += 1
+    text = " ".join(text_parts)
+    if not text:
+        raise InvalidInvocation
+    cmd.append("-i")
+    cmd.append(f"{input_key}={text}")
+    cmd.extend(passed)
+    return cmd
+
+
+def _build_task_command(rest: list[str], backend: str | None = None) -> list[str]:
+    return _build_text_input_command(rest, backend, TASK_WORKFLOW, "task")
+
+
+def _build_review_command(rest: list[str], backend: str | None = None) -> list[str]:
+    cmd = [RUN_PIPELINE]
+    if backend:
+        cmd += ["--backend", backend]
+    cmd.append(REVIEW_WORKFLOW)
+    i = 0
+    while i < len(rest):
+        arg = rest[i]
+        if arg == "--branch-diff":
+            cmd.append("-i")
+            cmd.append("branch-diff=true")
+        elif arg == "-i":
+            if i + 1 >= len(rest):
+                raise InvalidInvocation
+            cmd.append(arg)
+            cmd.append(rest[i + 1])
+            i += 2
+            continue
+        else:
+            cmd.append(arg)
+        i += 1
+    return cmd
+
+
+def print_usage(stream: Any = None) -> None:
+    """Print the usage text; defaults to stdout, pass sys.stderr for errors."""
+    if stream is None:
+        stream = sys.stdout
+    print(USAGE, file=stream)
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+    try:
+        try:
+            cmd = build_command(argv)
+        except HelpRequested:
+            print_usage()
+            return 0
+        except InvalidInvocation:
+            print_usage(sys.stderr)
+            return 1
+        except EditRequested:
+            # The edit flow never runs the backend CLI, so the
+            # tool-presence prerequisite check is skipped: a user who
+            # uninstalled the active backend must still be able to edit the
+            # config (e.g. to switch backends). The bootstrap render is
+            # best-effort on this path: a stale install marker with an
+            # INVALID config.yml must not gate the editor either — fixing a
+            # broken config is exactly what `edit` is for, and _run_edit
+            # re-validates when the editor closes (rolling back an invalid
+            # edit), so a failed bootstrap here cannot apply anything.
+            bootstrap.ensure_installed(_LAYOUT, check_prereqs=False)
+            return _run_edit(CONFIG, _LAYOUT)
+        except UninstallRequested as exc:
+            return uninstall.do_uninstall(_LAYOUT, exc.yes)
+        if bootstrap.ensure_installed(_LAYOUT) != 0:
+            return 1
+        try:
+            # os.execv replaces this process with run-pipeline.py, so its live
+            # output, timestamps and exit code pass through unchanged; it returns
+            # only when exec fails, which is why return 1 follows.
+            os.execv(cmd[0], cmd)
+        except OSError as exc:
+            print(f"error: cannot run {cmd[0]}: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        # Ctrl+C at a prompt (e.g. the uninstall confirmation) is a normal
+        # way to bail out: a quiet exit 130, not a traceback.
+        print("interrupted", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

modus_operandi/config.py

@@ -0,0 +1,199 @@
+"""Configuration: defaults, config.yml loading, merging and validation."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from . import InstallError
+
+DEFAULT_STATE_DIR = ".workflow"
+DEFAULT_MAX_FIX_ITERATIONS = 5
+DEFAULT_MAX_SRP_ITERATIONS = 5
+DEFAULT_MAX_BUG_ITERATIONS = 5
+DEFAULT_MAX_COMMENT_ITERATIONS = 5
+DEFAULT_MAX_IMPLEMENT_ITERATIONS = 2
+DEFAULT_MAX_QUESTIONS_ITERATIONS = 3
+DEFAULT_SHELL_TIMEOUT = 7200
+DEFAULT_REASONING = "max"
+DEFAULT_ADR_DIR = "architecture"
+DEFAULT_BACKEND = "opencode"
+BACKENDS = ("opencode", "cursor")
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "backend": DEFAULT_BACKEND,
+    "workflow": {
+        "state_dir": DEFAULT_STATE_DIR,
+        "max_fix_iterations": DEFAULT_MAX_FIX_ITERATIONS,
+        "max_srp_iterations": DEFAULT_MAX_SRP_ITERATIONS,
+        "max_bug_iterations": DEFAULT_MAX_BUG_ITERATIONS,
+        "max_comment_iterations": DEFAULT_MAX_COMMENT_ITERATIONS,
+        "max_implement_iterations": DEFAULT_MAX_IMPLEMENT_ITERATIONS,
+        "max_questions_iterations": DEFAULT_MAX_QUESTIONS_ITERATIONS,
+        "shell_timeout": DEFAULT_SHELL_TIMEOUT,
+        "adr_dir": DEFAULT_ADR_DIR,
+        "human_gates": True,
+        "use_serve": False,
+    },
+}
+
+
+def load_config(path: str | Path) -> dict[str, Any]:
+    # Config loading is the one place a YAML parse error can surface from user
+    # input, so it is converted to InstallError here — main() then stays flat
+    # without special-casing yaml types. A root that is valid YAML but not a
+    # mapping (a bare scalar or a list) is the same class of user error, and
+    # dict(raw) would otherwise raise an unhandled TypeError instead.
+    # PyYAML is a declared wheel dependency (pyproject.toml `dependencies`),
+    # so the import is unconditional.
+    with open(path, encoding="utf-8") as fh:
+        text = fh.read()
+    try:
+        raw = yaml.safe_load(text) or {}
+    except yaml.YAMLError as exc:
+        raise InstallError(f"invalid config.yml: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise InstallError("invalid config.yml: top-level must be a mapping")
+    return dict(raw)
+
+
+def opencode_models_complete(cfg: dict[str, Any]) -> bool:
+    """Whether the opencode section carries usable models for both roles.
+
+    The single predicate under which render.render_agents() writes the
+    opencode agent files; verify.check_files() requires those files under
+    the same condition, so a config whose opencode section is empty or
+    incomplete (valid when another backend is active) neither renders nor
+    demands the agent files.
+    """
+    models = (cfg.get("opencode") or {}).get("models") or {}
+    planner = models.get("planner") or {}
+    executor = models.get("executor") or {}
+    return bool(
+        planner.get("provider")
+        and planner.get("model")
+        and executor.get("provider")
+        and executor.get("model")
+    )
+
+
+def apply_defaults(raw: Any) -> dict[str, Any]:
+    # Same guard as load_config: raw may be None (treated as empty config) but
+    # any other non-mapping top level is a user error, not a TypeError.
+    if raw is not None and not isinstance(raw, dict):
+        raise InstallError("invalid config.yml: top-level must be a mapping")
+    cfg = dict(raw or {})
+    # Legacy top-level `models:` is folded into `opencode.models` so existing
+    # configs keep working; an explicit opencode section wins over the legacy
+    # key (the user is mid-migration and opencode is the section they wrote).
+    if "models" in cfg:
+        if "opencode" not in cfg:
+            cfg["opencode"] = {"models": cfg["models"]}
+        del cfg["models"]
+    cfg.setdefault("backend", DEFAULT_BACKEND)
+    workflow = cfg.get("workflow") or {}
+    if not isinstance(workflow, dict):
+        raise InstallError("invalid config.yml: workflow must be a mapping")
+    merged_workflow = dict(DEFAULT_CONFIG["workflow"])
+    merged_workflow.update(workflow)
+    cfg["workflow"] = merged_workflow
+    if "opencode" in cfg:
+        opencode = cfg["opencode"]
+        if not isinstance(opencode, dict):
+            raise InstallError("invalid config.yml: opencode must be a mapping")
+        models = opencode.get("models") or {}
+        if not isinstance(models, dict):
+            raise InstallError("invalid config.yml: opencode.models must be a mapping")
+        for role in ("planner", "executor"):
+            model = models.get(role) or {}
+            if not isinstance(model, dict):
+                raise InstallError(f"invalid config.yml: opencode.models.{role} must be a mapping")
+            model = dict(model)
+            model.setdefault("reasoning", DEFAULT_REASONING)
+            models[role] = model
+        opencode["models"] = models
+        cfg["opencode"] = opencode
+    if "cursor" in cfg:
+        cursor = cfg["cursor"]
+        if not isinstance(cursor, dict):
+            raise InstallError("invalid config.yml: cursor must be a mapping")
+        models = cursor.get("models") or {}
+        if not isinstance(models, dict):
+            raise InstallError("invalid config.yml: cursor.models must be a mapping")
+        for role in ("planner", "executor"):
+            model = models.get(role) or {}
+            if not isinstance(model, dict):
+                raise InstallError(f"invalid config.yml: cursor.models.{role} must be a mapping")
+            models[role] = model
+        cursor["models"] = models
+        cfg["cursor"] = cursor
+    return cfg
+
+
+def validate_config(cfg: dict[str, Any]) -> dict[str, Any]:
+    errors: list[str] = []
+    backend = cfg.get("backend")
+    if backend not in BACKENDS:
+        errors.append(f"backend must be one of: opencode, cursor (got {backend!r})")
+    # Only the active backend's models are strictly required (symmetric to
+    # the opencode provider/model/reasoning fields); the inactive section, if
+    # present, was already validated structurally by apply_defaults.
+    if backend == "opencode":
+        models = (cfg.get("opencode") or {}).get("models") or {}
+        for role in ("planner", "executor"):
+            model = models.get(role) or {}
+            for key in ("provider", "model", "reasoning"):
+                value = model.get(key)
+                if not value:
+                    errors.append(f"missing required key: opencode.models.{role}.{key}")
+                elif "<" in str(value) or ">" in str(value):
+                    errors.append(
+                        f"placeholder value in opencode.models.{role}.{key} - edit config.yml first"
+                    )
+    elif backend == "cursor":
+        models = (cfg.get("cursor") or {}).get("models") or {}
+        for role in ("planner", "executor"):
+            model = models.get(role) or {}
+            value = model.get("model")
+            if not value:
+                errors.append(f"missing required key: cursor.models.{role}.model")
+            elif "<" in str(value) or ">" in str(value):
+                errors.append(
+                    f"placeholder value in cursor.models.{role}.model - edit config.yml first"
+                )
+    workflow = cfg["workflow"]
+    for key in (
+        "max_fix_iterations",
+        "max_srp_iterations",
+        "max_bug_iterations",
+        "max_comment_iterations",
+        "max_implement_iterations",
+        "max_questions_iterations",
+    ):
+        value = workflow.get(key)
+        # type() is int, not isinstance: bool is a subclass of int, so
+        # `max_fix_iterations: true` must not pass the integer check — it
+        # would render as "True" into the generated workflows.
+        if type(value) is not int or value < 1:
+            errors.append(f"workflow.{key} must be an integer >= 1")
+    value = workflow.get("shell_timeout")
+    if type(value) is not int or value < 1:
+        errors.append("workflow.shell_timeout must be a positive number of seconds")
+    for key in ("state_dir", "adr_dir"):
+        value = workflow.get(key, "")
+        # The regex below is only meaningful for strings: str(None) is "None"
+        # and would pass it, silently pointing the workflow at "None/..." dirs.
+        if not isinstance(value, str):
+            errors.append(f"workflow.{key} must be a string")
+        elif not re.fullmatch(r"[A-Za-z0-9_./-]+", value):
+            errors.append(f"workflow.{key} contains unsupported characters")
+    if not isinstance(workflow.get("human_gates"), bool):
+        errors.append("workflow.human_gates must be a boolean")
+    if not isinstance(workflow.get("use_serve"), bool):
+        errors.append("workflow.use_serve must be a boolean")
+    if errors:
+        raise InstallError("invalid config.yml:\n  " + "\n  ".join(errors))
+    return cfg

modus_operandi/data/config.example.yml

@@ -0,0 +1,37 @@
+# modus-operandi configuration
+# On first run this file is copied to ~/.config/modus-operandi/config.yml.
+# Edit the values below, then re-apply with `modus-operandi edit` (dev: re-run install.py).
+
+backend: opencode          # active backend: opencode or cursor (per-run override: modus-operandi --backend cursor)
+
+opencode:                  # models for the opencode backend (legacy top-level `models:` is read as this section)
+  models:
+    planner:
+      provider: opencode              # opencode provider id: `opencode` = OpenCode Zen (free models work with no setup),
+                                      # `opencode-go` = OpenCode Go ($10/month subscription, OPENCODE_API_KEY required)
+      model: big-pickle               # strong model for planning and review (free on Zen; paid: deepseek-v4-pro, gpt-5.x, ...)
+      reasoning: max                  # reasoning effort passed to the provider (e.g. minimal, low, high, max)
+    executor:
+      provider: opencode
+      model: big-pickle               # model for implementation (free on Zen; paid: deepseek-v4-flash, ...)
+      reasoning: max                  # reasoning effort passed to the provider
+
+cursor:                    # models for the cursor backend (passed to cursor-agent as --model <slug>)
+  models:
+    planner:
+      model: composer-2              # strong model for planning and review (Cursor model slug)
+    executor:
+      model: composer-2              # cheap/fast model for implementation (Cursor model slug)
+
+workflow:
+  state_dir: .workflow           # task artifact directory inside a project
+  max_fix_iterations: 5          # ceiling for the unified parallel review-fix loop (SRP, bugs, general review, comments, ADR-0009)
+  max_srp_iterations: 5          # legacy: no longer binds a separate SRP loop (kept for backward compatibility)
+  max_bug_iterations: 5          # legacy: no longer binds a separate bug loop (kept for backward compatibility)
+  max_comment_iterations: 5      # legacy: no longer binds a separate comment loop (kept for backward compatibility)
+  max_implement_iterations: 2    # ceiling for the implement verify/retry loop (guard against an empty implementation)
+  max_questions_iterations: 3    # ceiling for the task-pipeline executor questions loop
+  shell_timeout: 7200            # per-step timeout in seconds for agent steps (2h)
+  adr_dir: architecture          # directory (repo-relative) where approved ADRs are saved
+  human_gates: true              # false = gates auto-approve (non-interactive runs)
+  use_serve: false               # true = run-agent.sh passes --attach http://localhost:4096

modus_operandi/data/pipeline_scripts/adr-task-id.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# adr-task-id.sh - task-pipeline generate-task-id step.
+#
+# Uses the explicit task id when given; otherwise asks the executor for a
+# short English kebab-case slug (name-task.sh, one-shot) and appends a
+# timestamp. Creates the task dir and points <state_dir>/tasks/current at it.
+# The workflow never embeds shell logic (CONTRIBUTING.md), so the id
+# derivation lives here. The task_id value was already validated by
+# validate_inputs.py (validate-task-id step) before it reaches this script.
+#
+# Usage: adr-task-id.sh <state_dir> <task_id> <feature>
+set -euo pipefail
+
+[ $# -eq 3 ] || { echo "usage: $0 <state_dir> <task_id> <feature>" >&2; exit 2; }
+STATE_DIR="$1"
+TASK_ID="$2"
+FEATURE="$3"
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+mkdir -p "$STATE_DIR/tasks"
+if [ -n "$TASK_ID" ]; then
+  tid="$TASK_ID"
+else
+  slug=$("$SCRIPT_DIR/name-task.sh" "$FEATURE")
+  slug=$(printf '%s' "$slug" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//' | cut -c1-40)
+  [ -n "$slug" ] || slug=task
+  tid="$slug-$(date +%Y%m%d-%H%M)"
+fi
+mkdir -p "$STATE_DIR/tasks/$tid"
+ln -sfn "$tid" "$STATE_DIR/tasks/current"
+echo "task id: $tid"