modus-operandi 0.2.0__tar.gz → 0.2.2__tar.gz

{modus_operandi-0.2.0 → modus_operandi-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modus-operandi
-Version: 0.2.0
+Version: 0.2.2
 Summary: Spec-driven planner -> executor pipelines for opencode and cursor
 Author: Denis Riazantsev
 Author-email: Denis Riazantsev <metacodeine@gmail.com>
@@ -24,6 +24,9 @@ Description-Content-Type: text/markdown
 
 # Modus Operandi 🤌
 
+[![PyPI version](https://img.shields.io/pypi/v/modus-operandi.svg)](https://pypi.org/project/modus-operandi/)
+[![Python versions](https://img.shields.io/pypi/pyversions/modus-operandi.svg)](https://pypi.org/project/modus-operandi/)
+
 Automate spec-driven "planner -> executor" workflows in LLM clients (opencode
 and cursor): task planning, task implementing and code review.
 
@@ -120,6 +123,10 @@ By default, opencode is used. If you need the cursor backend, use the
 modus-operandi --backend cursor task "<task-description>"
 ```
 
+Cursor runs on its default `composer-2` model for planning, review and
+implementation when no `cursor:` section is configured yet; set your own
+model slugs with `modus-operandi edit`.
+
 ### Config
 
 ```shell

{modus_operandi-0.2.0 → modus_operandi-0.2.2}/README.md

@@ -1,5 +1,8 @@
 # Modus Operandi 🤌
 
+[![PyPI version](https://img.shields.io/pypi/v/modus-operandi.svg)](https://pypi.org/project/modus-operandi/)
+[![Python versions](https://img.shields.io/pypi/pyversions/modus-operandi.svg)](https://pypi.org/project/modus-operandi/)
+
 Automate spec-driven "planner -> executor" workflows in LLM clients (opencode
 and cursor): task planning, task implementing and code review.
 
@@ -96,6 +99,10 @@ By default, opencode is used. If you need the cursor backend, use the
 modus-operandi --backend cursor task "<task-description>"
 ```
 
+Cursor runs on its default `composer-2` model for planning, review and
+implementation when no `cursor:` section is configured yet; set your own
+model slugs with `modus-operandi edit`.
+
 ### Config
 
 ```shell

{modus_operandi-0.2.0 → modus_operandi-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "modus-operandi"
-version = "0.2.0"
+version = "0.2.2"
 description = "Spec-driven planner -> executor pipelines for opencode and cursor"
 readme = "README.md"
 requires-python = ">=3.12"

{modus_operandi-0.2.0 → modus_operandi-0.2.2}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "modus-operandi"
-version = "0.2.0"
+version = "0.2.2"
 description = "Spec-driven planner -> executor pipelines for opencode and cursor"
 readme = "README.md"
 requires-python = ">=3.12"

{modus_operandi-0.2.0 → modus_operandi-0.2.2}/src/modus_operandi/__init__.py

@@ -17,7 +17,7 @@ from .paths import Paths
 # defined in this module.)
 __all__ = ["InstallError", "Paths", "__version__"]
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 
 class InstallError(Exception):

{modus_operandi-0.2.0 → modus_operandi-0.2.2}/src/modus_operandi/config.py

@@ -23,6 +23,24 @@ DEFAULT_ADR_DIR = "architecture"
 DEFAULT_BACKEND = "opencode"
 BACKENDS = ("opencode", "cursor")
 
+# The shipped per-backend role model defaults, mirroring config.example.yml
+# (opencode: the free OpenCode Zen big-pickle; cursor: Cursor's default
+# composer-2). apply_defaults fills the ACTIVE backend's missing role models
+# from these, so switching backends with `modus-operandi edit` works out of
+# the box even on a config created before the backend's section existed
+# (e.g. a legacy pre-cursor config); an existing value (even a placeholder)
+# is never overwritten, so validation still catches placeholders.
+DEFAULT_MODELS: dict[str, dict[str, dict[str, str]]] = {
+    "opencode": {
+        "planner": {"provider": "opencode", "model": "big-pickle", "reasoning": DEFAULT_REASONING},
+        "executor": {"provider": "opencode", "model": "big-pickle", "reasoning": DEFAULT_REASONING},
+    },
+    "cursor": {
+        "planner": {"model": "composer-2"},
+        "executor": {"model": "composer-2"},
+    },
+}
+
 DEFAULT_CONFIG: dict[str, Any] = {
     "backend": DEFAULT_BACKEND,
     "workflow": {
@@ -51,17 +69,27 @@ def load_config(path: str | Path) -> dict[str, Any]:
     # 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.
+    # The file is read as BYTES so PyYAML detects the encodings a desktop
+    # editor can save (UTF-8, UTF-16/UTF-32 with BOM); a BOM-less UTF-16 save
+    # falls back to an explicit decode — otherwise `modus-operandi edit`
+    # rejected (and rolled back) a config saved as UTF-16 by a macOS editor.
     # 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:
+        raw = Path(path).read_bytes()
+    except OSError as exc:
+        raise InstallError(f"cannot read config.yml: {exc}") from exc
+    try:
+        try:
+            parsed = yaml.safe_load(raw)
+        except yaml.YAMLError:
+            parsed = yaml.safe_load(raw.decode("utf-16"))
+    except (UnicodeDecodeError, yaml.YAMLError) as exc:
         raise InstallError(f"invalid config.yml: {exc}") from exc
-    if not isinstance(raw, dict):
+    raw_cfg = parsed or {}
+    if not isinstance(raw_cfg, dict):
         raise InstallError("invalid config.yml: top-level must be a mapping")
-    return dict(raw)
+    return dict(raw_cfg)
 
 
 def opencode_models_complete(cfg: dict[str, Any]) -> bool:
@@ -84,6 +112,45 @@ def opencode_models_complete(cfg: dict[str, Any]) -> bool:
     )
 
 
+def _fill_default_models(cfg: dict[str, Any], backend: str) -> None:
+    """Fill the ACTIVE backend's missing role models with the shipped defaults.
+
+    Only the active backend is completed (DEFAULT_MODELS): switching backends
+    with `modus-operandi edit` must not fail on a config that predates the
+    target backend's section (e.g. a legacy config without a cursor section),
+    while the inactive section stays untouched — an empty opencode section
+    keeps rendering no agent files. Existing values are never overwritten (a
+    placeholder value stays and fails validation), and a structurally invalid
+    section is left alone for the per-section validation below to reject.
+    """
+    defaults = DEFAULT_MODELS.get(backend)
+    if defaults is None:
+        return
+    section = cfg.get(backend)
+    if section is None:
+        section = {}
+    if not isinstance(section, dict):
+        return
+    models = section.get("models")
+    if models is None:
+        models = {}
+    if not isinstance(models, dict):
+        return
+    for role in ("planner", "executor"):
+        model = models.get(role)
+        if model is None:
+            model = {}
+        if not isinstance(model, dict):
+            continue
+        merged = dict(defaults[role])
+        for key, value in model.items():
+            if value is not None:
+                merged[key] = value
+        models[role] = merged
+    section["models"] = models
+    cfg[backend] = section
+
+
 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.
@@ -98,6 +165,10 @@ def apply_defaults(raw: Any) -> dict[str, Any]:
             cfg["opencode"] = {"models": cfg["models"]}
         del cfg["models"]
     cfg.setdefault("backend", DEFAULT_BACKEND)
+    # Complete the active backend's models (see _fill_default_models): the
+    # active section is always usable out of the box, the inactive one is
+    # validated structurally below, nothing more.
+    _fill_default_models(cfg, cfg["backend"])
     workflow = cfg.get("workflow") or {}
     if not isinstance(workflow, dict):
         raise InstallError("invalid config.yml: workflow must be a mapping")

{modus_operandi-0.2.0 → modus_operandi-0.2.2}/src/modus_operandi/data/pipeline_scripts/config_invocation.py

@@ -26,6 +26,24 @@ CONFIG_PATH = Path(
 # fallback for an invalid config value).
 BACKENDS = ("opencode", "cursor")
 
+# The shipped per-backend default role model slugs, mirroring
+# modus_operandi/config.py (DEFAULT_MODELS). The wrapper reads the raw YAML
+# without apply_defaults, so a model missing from the ACTIVE backend's
+# section (a legacy config without a cursor section, a --backend override on
+# a config that does not configure the backend) falls back to the shipped
+# default instead of exporting an empty MO_*_MODEL that fails deep in
+# run-agent.sh. Keep the two in sync.
+_DEFAULT_MODELS: dict[str, dict[str, dict[str, str]]] = {
+    "opencode": {
+        "planner": {"model": "big-pickle"},
+        "executor": {"model": "big-pickle"},
+    },
+    "cursor": {
+        "planner": {"model": "composer-2"},
+        "executor": {"model": "composer-2"},
+    },
+}
+
 
 def normalize_config(cfg: dict[str, Any]) -> dict[str, Any]:
     """Fold the legacy top-level `models:` into `opencode.models`.
@@ -90,10 +108,14 @@ def sound_settings(cfg: dict[str, Any], config_path: Path) -> tuple[bool, str]:
 
 
 def role_model(cfg: dict[str, Any], backend: str, role: str) -> str:
-    """Model slug of a role under the active backend ("" when unset).
+    """Model slug of a role under the active backend.
 
     The opencode agent files carry the opencode model; the exported value is
-    only consumed by the cursor branch of run-agent.sh/name-task.sh.
+    only consumed by the cursor branch of run-agent.sh/name-task.sh. A model
+    missing from the active backend's section falls back to the shipped
+    default (_DEFAULT_MODELS, mirroring the installer's apply_defaults), so a
+    legacy config or a `--backend` override on a config that does not
+    configure the backend still runs instead of exporting an empty value.
     """
     section = cfg.get("cursor") if backend == "cursor" else cfg.get("opencode")
     if not isinstance(section, dict):
@@ -107,30 +129,64 @@ def role_model(cfg: dict[str, Any], backend: str, role: str) -> str:
     model = models.get(role)
     model = model if isinstance(model, dict) else {}
     value = model.get("model")
-    return value if isinstance(value, str) else ""
+    if isinstance(value, str) and value:
+        return value
+    default = _DEFAULT_MODELS.get(backend, {}).get(role, {}).get("model")
+    return default if isinstance(default, str) else ""
 
 
 def load_config(config_path: Path | None = None) -> dict[str, Any]:
-    """Read the installed config.yml into a dict, or {} on any failure.
+    """Read the installed config.yml into a dict, or {} when it is missing.
 
     config_path defaults to the module's CONFIG_PATH; the run-pipeline entry
     passes its own CONFIG_PATH explicitly so a runtime override (e.g. tests
-    pointing the wrapper at another file) is honored. A missing or unreadable
-    file degrades to the documented defaults, so a hand-invoked wrapper (or a
-    config deleted after install) still runs.
+    pointing the wrapper at another file) is honored. A MISSING file degrades
+    to the documented defaults, so a hand-invoked wrapper (or a config
+    deleted after install) still runs. An EXISTING file that cannot be read
+    or parsed raises ValueError with a user-facing explanation: silently
+    running the pipeline with the opencode defaults on a broken config is
+    what hid backend misconfiguration (a config that fails to load made
+    `backend: cursor` invisible, so the run used opencode and exported empty
+    role models), so a broken config now aborts before the run starts —
+    mirroring sound_settings. The file is read as BYTES: PyYAML detects the
+    UTF-8 and UTF-16/UTF-32 (with BOM) encodings a desktop text editor can
+    save, so a macOS TextEdit UTF-16 save still parses instead of failing.
     """
     path = config_path if config_path is not None else CONFIG_PATH
     try:
-        text = path.read_text(encoding="utf-8")
-    except OSError:
+        raw = path.read_bytes()
+    except FileNotFoundError:
         return {}
-    try:
-        import yaml  # pyproject.toml declares pyyaml as a package dependency
-
-        data = yaml.safe_load(text) or {}
-    except Exception:
+    except OSError as exc:
+        raise ValueError(f"cannot read config {path}: {exc}") from exc
+    data = _safe_yaml_load(raw)
+    if data is None:
         return {}
-    return data if isinstance(data, dict) else {}
+    if not isinstance(data, dict):
+        raise ValueError(
+            f"invalid config.yml at {path}: top-level must be a mapping, got {type(data).__name__}"
+        )
+    return data
+
+
+def _safe_yaml_load(raw: bytes) -> Any:
+    """Parse config bytes into a value, tolerating editor-saved encodings.
+
+    PyYAML given BYTES detects UTF-8 (plain and with BOM) and UTF-16/UTF-32
+    with BOM natively; a BOM-less UTF-16 file (an editor that saves
+    "UTF-16 LE") falls back to an explicit decode. Raises ValueError with
+    the parse error when neither works.
+    """
+    import yaml  # pyproject.toml declares pyyaml as a package dependency
+
+    try:
+        return yaml.safe_load(raw)
+    except yaml.YAMLError:
+        pass
+    try:
+        return yaml.safe_load(raw.decode("utf-16"))
+    except (UnicodeDecodeError, yaml.YAMLError) as exc:
+        raise ValueError(f"invalid config.yml: cannot parse the file: {exc}") from exc
 
 
 def build_specify_invocation(

{modus_operandi-0.2.0 → modus_operandi-0.2.2}/src/modus_operandi/data/pipeline_scripts/editor.py

@@ -58,21 +58,25 @@ def resolve_editor() -> list[str] | None:
 def resolve_feedback_editor() -> tuple[str, list[str]] | None:
     """Resolve the platform editor for the feedback gates (ADR-0011).
 
-    Returns (mode, cmd): mode is "waited" — run the editor blocking and
-    answer the gate with `continue` on close — or "detached" — launch it in
-    a separate window and leave the gate interactive (the user presses
-    `continue`). None means no editor is available at all.
+    Returns (mode, cmd): mode is "detached" — launch the editor in a
+    separate window and leave the gate interactive (the user presses
+    `continue` in the terminal) — or "waited" — run the editor blocking in
+    the terminal and answer the gate with `continue` on close. None means
+    no editor is available at all.
 
-    macOS: TextEdit via `open -a TextEdit -W` (always installed; the -W flag
-    blocks until the app closes), waited. Linux: GNOME Text Editor in a
-    separate window — Flatpak first (checked via `flatpak info
+    macOS: TextEdit via `open -a TextEdit` (always installed), detached —
+    the -W flag is deliberately NOT used: it waits for the whole app to
+    quit (closing the document window is not enough, and an already-running
+    TextEdit makes `open -W` block until THAT instance exits), which hung
+    the run at the feedback gate with no menu on screen. Linux: GNOME Text
+    Editor in a separate window — Flatpak first (checked via `flatpak info
     org.gnome.TextEditor`), then the RPM binary, then the generic desktop
     opener (gio, then xdg-open) — all detached, since these launchers return
     immediately. Fallback: the terminal chain ($VISUAL, $EDITOR, nano, vi),
     waited.
     """
     if sys.platform == "darwin":
-        return "waited", ["open", "-a", "TextEdit", "-W"]
+        return "detached", ["open", "-a", "TextEdit"]
     if sys.platform.startswith("linux"):
         if shutil.which("flatpak"):
             try:

{modus_operandi-0.2.0 → modus_operandi-0.2.2}/src/modus_operandi/data/pipeline_scripts/feedback_editor.py

@@ -68,14 +68,14 @@ def open_feedback_editor(
     in the platform editor and, on editor close,
     answers the gate with `continue` so the workflow continues (the revise
     step reads feedback.md).
-    The editor resolution (editor.py) returns a mode: "waited" (macOS
-    TextEdit or the terminal chain) runs the editor blocking and the wrapper
-    answers the gate; "detached" (Linux GUI in a separate window) launches
-    the editor and leaves the gate interactive — the user closes the window
-    and presses `continue`. Returns True when the wrapper answered the gate;
-    False on fallback — no TTY, no editor, or a detached launch — where the
-    file is still created, forwarding is left running and the gate stays
-    interactive for manual input.
+    The editor resolution (editor.py) returns a mode: "detached" (macOS
+    TextEdit, Linux GUI in a separate window) launches the editor and
+    leaves the gate interactive — the user closes the window and presses
+    `continue`; "waited" (the terminal chain) runs the editor blocking and
+    the wrapper answers the gate. Returns True when the wrapper answered
+    the gate; False on fallback — no TTY, no editor, or a detached launch —
+    where the file is still created, forwarding is left running and the
+    gate stays interactive for manual input.
     """
     task_dir = Path.cwd() / state_dir / "tasks" / "current"
     source_doc: Path | None = None

{modus_operandi-0.2.0 → modus_operandi-0.2.2}/src/modus_operandi/data/pipeline_scripts/run_pipeline.py

@@ -18,11 +18,15 @@ to specify (keeping sys.stdin.isatty() True inside it) and terminal input is
 forwarded into the master end, so interactive gates keep working while the
 wrapper can answer the feedback gate itself. When that gate opens
 the wrapper creates <state_dir>/tasks/current/feedback.md (never overwriting
-an existing file), opens it in the terminal editor ($VISUAL, then $EDITOR,
-then nano, then vi), and on editor close answers the gate with `continue` so
-the workflow resumes (study-revise reads feedback.md). If no editor can run
-(non-TTY or none found), the file is still created and the gate stays
-interactive for manual input. On a non-TTY run no pty is used and specify
+an existing file) and opens it in the platform editor — macOS TextEdit and
+the Linux GUI open in a separate window and the run NEVER waits for the
+editor: the gate stays interactive and the user answers it in the terminal
+(`continue`/`abort`) after closing the editor; without a GUI the editor runs
+in the terminal ($VISUAL, then $EDITOR, then nano, then vi) and the wrapper
+answers the gate with `continue` on editor close so the workflow resumes
+(study-revise reads feedback.md). If no editor can run (non-TTY or none
+found), the file is still created and the gate stays interactive for manual
+input. On a non-TTY run no pty is used and specify
 keeps the inherited stdin, so gates keep going PAUSED exactly as before.
 
 When the run finishes (success, failure or abort alike) the wrapper prints a
@@ -218,8 +222,15 @@ def main() -> int:
     # Map the installed config + argv to the specify invocation; main() only
     # orchestrates the live run from the result. CONFIG_PATH is passed
     # explicitly so a runtime override of this module's CONFIG_PATH (e.g. by
-    # tests) is honored by the config read.
-    cfg = load_config(CONFIG_PATH)
+    # tests) is honored by the config read. An existing but unreadable or
+    # invalid config aborts with an explanation instead of silently running
+    # with the opencode defaults (a broken config used to make `backend:
+    # cursor` invisible and export empty role models).
+    try:
+        cfg = load_config(CONFIG_PATH)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
     # The sound section is validated before the run starts (ADR-0018): an
     # invalid sound setting aborts with an explanation, not a silent degrade.
     try:

{modus_operandi-0.2.0 → modus_operandi-0.2.2}/src/modus_operandi/data/workflows/task-pipeline.yml

@@ -121,9 +121,9 @@ steps:
             message: >-
               Feedback on the motivation study is collected in
               {{ inputs.state_dir }}/tasks/current/feedback.md — the wrapper opens it
-              in your editor: on macOS the run continues automatically when the
-              editor closes; on Linux close the editor window and choose
-              continue. If no editor opened, create the file manually
+              in your editor; the run never waits for the editor: edit and
+              save the file, close the editor window, then choose continue
+              in the terminal. If no editor opened, create the file manually
               and write your feedback, then choose continue. The planner
               will update study.md accordingly.
             options: [continue, abort]

{modus_operandi-0.2.0 → modus_operandi-0.2.2}/src/modus_operandi/editor.py

@@ -58,21 +58,25 @@ def resolve_editor() -> list[str] | None:
 def resolve_feedback_editor() -> tuple[str, list[str]] | None:
     """Resolve the platform editor for the feedback gates (ADR-0011).
 
-    Returns (mode, cmd): mode is "waited" — run the editor blocking and
-    answer the gate with `continue` on close — or "detached" — launch it in
-    a separate window and leave the gate interactive (the user presses
-    `continue`). None means no editor is available at all.
+    Returns (mode, cmd): mode is "detached" — launch the editor in a
+    separate window and leave the gate interactive (the user presses
+    `continue` in the terminal) — or "waited" — run the editor blocking in
+    the terminal and answer the gate with `continue` on close. None means
+    no editor is available at all.
 
-    macOS: TextEdit via `open -a TextEdit -W` (always installed; the -W flag
-    blocks until the app closes), waited. Linux: GNOME Text Editor in a
-    separate window — Flatpak first (checked via `flatpak info
+    macOS: TextEdit via `open -a TextEdit` (always installed), detached —
+    the -W flag is deliberately NOT used: it waits for the whole app to
+    quit (closing the document window is not enough, and an already-running
+    TextEdit makes `open -W` block until THAT instance exits), which hung
+    the run at the feedback gate with no menu on screen. Linux: GNOME Text
+    Editor in a separate window — Flatpak first (checked via `flatpak info
     org.gnome.TextEditor`), then the RPM binary, then the generic desktop
     opener (gio, then xdg-open) — all detached, since these launchers return
     immediately. Fallback: the terminal chain ($VISUAL, $EDITOR, nano, vi),
     waited.
     """
     if sys.platform == "darwin":
-        return "waited", ["open", "-a", "TextEdit", "-W"]
+        return "detached", ["open", "-a", "TextEdit"]
     if sys.platform.startswith("linux"):
         if shutil.which("flatpak"):
             try: