modus-operandi 0.6.0__tar.gz

modus_operandi-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denis Riazantsev (metacodeine@gmail.com)
+
+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.

modus_operandi-0.6.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: modus-operandi
+Version: 0.6.0
+Summary: Spec-driven planner -> executor pipelines for opencode and cursor
+Author: Denis Riazantsev
+Author-email: Denis Riazantsev <metacodeine@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Dist: specify-cli>=0.16
+Requires-Dist: pyyaml>=6.0
+Requires-Python: >=3.12
+Project-URL: repository, https://github.com/DenisRyazantsev/modus-operandi
+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.
+
+## Quick start
+
+```shell
+pip install modus-operandi
+modus-operandi task "<task-description>"
+```
+
+No configuration needed: the defaults use the free OpenCode Zen model
+`opencode/big-pickle` for planning, review and implementation, which works
+out of the box. To switch models or backends, run `modus-operandi edit`.
+
+## Install
+
+`modus-operandi` works right after install: the first run renders the pipeline
+files (agents, scripts, workflows, prompts) into `~/.config/modus-operandi/` and
+`~/.config/opencode/`, and creates `~/.config/modus-operandi/config.yml` from the
+example. Updates arrive through PyPI (`pip install -U modus-operandi`); the render
+is re-applied automatically on the next run.
+
+Requirements: Python >= 3.12, and one backend CLI on PATH — `opencode`
+(default) or `cursor-agent` (see `--backend cursor` below).
+
+The dev flow (`python3 install.py` from a checkout) additionally installs a
+checkout-based `modus-operandi` command into `~/.local/bin` and keeps that
+directory on PATH in your existing shell rc files (`~/.bashrc`, `~/.zshrc`,
+`~/.profile`), so the command is available in every newly opened terminal.
+
+## Usage
+
+### Task
+
+If you have a workflow like this
+
+```
+1. Studying the motivation of the task with a planner-agent
+2. Creating an ADR
+3. Writing an implementation plan for the executor
+4. The executor-agent asking clarifying questions about the task
+5. The planner-agent answering these questions
+6. Implementing the task
+7. Reviewing for SRP violations
+8. Reviewing for bugs
+9. General review (correctness and quality)
+10. Comment review (readability)
+11. Tests review (the tests for the change, judged against the test conventions on machine-generated coverage and latency reports)
+12. Fixing the issues found
+13. The executor writing a final summary of what was done
+```
+
+The ADR records the decision (what and why) and is published to the
+`architecture/` directory at the end of the run in its final version; the
+implementation plan stays internal to the executor.
+
+then you can use this command
+
+```shell
+modus-operandi task "<task-description>"
+```
+
+The description can also come from a file: `modus-operandi task path/to/description.md`
+(a single argument naming an existing file is read as the description; file
+and inline text input are mutually exclusive).
+
+### Review
+
+If you have a workflow like this
+
+```
+1. Reviewing the whole project for SRP violations
+2. Reviewing the whole project for bugs
+3. Comment review (readability)
+4. Tests review (the tests for the change, judged against the test conventions on machine-generated coverage and latency reports)
+5. Fixing the issues found
+6. The executor writing a final summary of what was done
+```
+
+then you can use this command
+
+```shell
+modus-operandi review
+```
+
+To review only the changes between the current branch and the default branch:
+
+```shell
+modus-operandi review --branch-diff
+```
+
+### Backend
+
+By default, opencode is used. If you need the cursor backend, use the
+`--backend cursor` flag:
+
+```shell
+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 edit
+```
+
+opens `~/.config/modus-operandi/config.yml` in your terminal editor. On save and
+close it validates the file: a valid config is applied, an invalid one is
+rolled back and the error is reported with its line number; a config left
+unchanged is not re-applied.
+
+## Uninstall
+
+```shell
+modus-operandi uninstall
+pip uninstall modus-operandi
+```
+
+removes the rendered pipeline files (`~/.config/modus-operandi` and the modus-operandi
+files under `~/.config/opencode`) — run `pip uninstall modus-operandi` afterwards
+to remove the package itself.

modus_operandi-0.6.0/README.md

@@ -0,0 +1,130 @@
+# 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.
+
+## Quick start
+
+```shell
+pip install modus-operandi
+modus-operandi task "<task-description>"
+```
+
+No configuration needed: the defaults use the free OpenCode Zen model
+`opencode/big-pickle` for planning, review and implementation, which works
+out of the box. To switch models or backends, run `modus-operandi edit`.
+
+## Install
+
+`modus-operandi` works right after install: the first run renders the pipeline
+files (agents, scripts, workflows, prompts) into `~/.config/modus-operandi/` and
+`~/.config/opencode/`, and creates `~/.config/modus-operandi/config.yml` from the
+example. Updates arrive through PyPI (`pip install -U modus-operandi`); the render
+is re-applied automatically on the next run.
+
+Requirements: Python >= 3.12, and one backend CLI on PATH — `opencode`
+(default) or `cursor-agent` (see `--backend cursor` below).
+
+The dev flow (`python3 install.py` from a checkout) additionally installs a
+checkout-based `modus-operandi` command into `~/.local/bin` and keeps that
+directory on PATH in your existing shell rc files (`~/.bashrc`, `~/.zshrc`,
+`~/.profile`), so the command is available in every newly opened terminal.
+
+## Usage
+
+### Task
+
+If you have a workflow like this
+
+```
+1. Studying the motivation of the task with a planner-agent
+2. Creating an ADR
+3. Writing an implementation plan for the executor
+4. The executor-agent asking clarifying questions about the task
+5. The planner-agent answering these questions
+6. Implementing the task
+7. Reviewing for SRP violations
+8. Reviewing for bugs
+9. General review (correctness and quality)
+10. Comment review (readability)
+11. Tests review (the tests for the change, judged against the test conventions on machine-generated coverage and latency reports)
+12. Fixing the issues found
+13. The executor writing a final summary of what was done
+```
+
+The ADR records the decision (what and why) and is published to the
+`architecture/` directory at the end of the run in its final version; the
+implementation plan stays internal to the executor.
+
+then you can use this command
+
+```shell
+modus-operandi task "<task-description>"
+```
+
+The description can also come from a file: `modus-operandi task path/to/description.md`
+(a single argument naming an existing file is read as the description; file
+and inline text input are mutually exclusive).
+
+### Review
+
+If you have a workflow like this
+
+```
+1. Reviewing the whole project for SRP violations
+2. Reviewing the whole project for bugs
+3. Comment review (readability)
+4. Tests review (the tests for the change, judged against the test conventions on machine-generated coverage and latency reports)
+5. Fixing the issues found
+6. The executor writing a final summary of what was done
+```
+
+then you can use this command
+
+```shell
+modus-operandi review
+```
+
+To review only the changes between the current branch and the default branch:
+
+```shell
+modus-operandi review --branch-diff
+```
+
+### Backend
+
+By default, opencode is used. If you need the cursor backend, use the
+`--backend cursor` flag:
+
+```shell
+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 edit
+```
+
+opens `~/.config/modus-operandi/config.yml` in your terminal editor. On save and
+close it validates the file: a valid config is applied, an invalid one is
+rolled back and the error is reported with its line number; a config left
+unchanged is not re-applied.
+
+## Uninstall
+
+```shell
+modus-operandi uninstall
+pip uninstall modus-operandi
+```
+
+removes the rendered pipeline files (`~/.config/modus-operandi` and the modus-operandi
+files under `~/.config/opencode`) — run `pip uninstall modus-operandi` afterwards
+to remove the package itself.

modus_operandi-0.6.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["uv_build >= 0.12.1, <0.13.0"]
+build-backend = "uv_build"
+
+[project]
+name = "modus-operandi"
+version = "0.6.0"
+description = "Spec-driven planner -> executor pipelines for opencode and cursor"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Build Tools",
+]
+dependencies = [
+    "specify-cli>=0.16",
+    "pyyaml>=6.0",
+]
+
+[[project.authors]]
+name = "Denis Riazantsev"
+email = "metacodeine@gmail.com"
+
+[project.urls]
+repository = "https://github.com/DenisRyazantsev/modus-operandi"
+
+[project.scripts]
+modus-operandi = "modus_operandi.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest~=9.1.1",
+    "ruff~=0.16.4",
+    "mypy~=2.3.1",
+    "coverage~=7.6",
+    "types-PyYAML==6.0.12.20260815",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+extend-include = [".github/scripts/*.py"]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "W",
+    "B",
+    "UP",
+    "SIM",
+]
+
+[tool.pytest.ini_options]
+python_files = [
+    "tests/test_*.py",
+    "tests/*/test_*.py",
+    "tests/*_test.py",
+    "tests/*/*_test.py",
+]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+explicit_package_bases = true
+files = ["."]
+mypy_path = [
+    "src",
+    "src/modus_operandi/data/pipeline_scripts",
+    ".",
+]

modus_operandi-0.6.0/pyproject.toml.orig

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["uv_build >= 0.12.1, <0.13.0"]
+build-backend = "uv_build"
+
+[project]
+name = "modus-operandi"
+version = "0.6.0"
+description = "Spec-driven planner -> executor pipelines for opencode and cursor"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Denis Riazantsev", email = "metacodeine@gmail.com" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Build Tools",
+]
+dependencies = ["specify-cli>=0.16", "pyyaml>=6.0"]
+
+[project.urls]
+repository = "https://github.com/DenisRyazantsev/modus-operandi"
+
+[project.scripts]
+modus-operandi = "modus_operandi.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest~=9.1.1",
+    "ruff~=0.16.4",
+    "mypy~=2.3.1",
+    # coverage.py >= 7.6 carries per-function data in its JSON report
+    # (test_reports.py parses it for the tests review kind, ADR-0022). The
+    # 7.x line is pinned: a future 8.x could reshape that JSON.
+    "coverage~=7.6",
+    # types-PyYAML does not follow semver: the version is the targeted
+    # PyYAML version + a typeshed calver (date) suffix, and any stub update
+    # can change type-checking results. Pin exactly.
+    "types-PyYAML==6.0.12.20260815",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+lint.select = ["E", "F", "I", "W", "B", "UP", "SIM"]
+# CI scripts live in the hidden .github/ tree, which ruff skips by default;
+# they are first-class code and must be linted like everything else.
+extend-include = [".github/scripts/*.py"]
+
+[tool.pytest.ini_options]
+# The whole suite lives under tests/; the root-level report generator
+# (test_reports.py) matches the default `test_*.py` pattern and must not be
+# collected as a test module by an argument-less `uv run pytest`. The
+# patterns are matched against the repo-root-relative path (a `*` crosses
+# path separators, so the second pattern covers every nesting depth).
+python_files = [
+    "tests/test_*.py",
+    "tests/*/test_*.py",
+    "tests/*_test.py",
+    "tests/*/*_test.py",
+]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+# The standalone data scripts are not part of the modus_operandi package (no
+# __init__.py under data/): with explicit package bases mypy maps them only
+# through mypy_path, so their sibling imports resolve to the same module
+# names the scripts use at runtime.
+explicit_package_bases = true
+# Everything is checked: the whole repo tree, no whitelist, no exclude.
+files = ["."]
+# The standalone scripts import each other from the same directory (e.g.
+# save_adr.py imports adr_utils/agent_call/task_utils); point mypy at it so
+# those sibling imports resolve. "src" is the explicit package base of the
+# modus_operandi package.
+mypy_path = ["src", "src/modus_operandi/data/pipeline_scripts", "."]

modus_operandi-0.6.0/src/modus_operandi/__init__.py

@@ -0,0 +1,26 @@
+"""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. The checkout
+carries the 0.0.0.dev0 placeholder (ADR-0018); CI stamps the tag name at
+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.6.0"
+
+
+class InstallError(Exception):
+    """User-facing failure of the install/bootstrap flow."""
+
+    pass

modus_operandi-0.6.0/src/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