dotagents-cli 0.7.2__tar.gz → 0.7.3__tar.gz

{dotagents_cli-0.7.2 → dotagents_cli-0.7.3}/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.7.3] - 2026-10-04
+
+### Changed
+
+- The command guide and the shipped API header now say that every command except
+  `env`, built-in or discovered, is served as an MCP tool when `dotagents` starts with
+  `DOTAGENTS_MCP=stdio`, and that `AGENT_HELP=1` turns `--help` into a JSON document.
+  The authoring guide asks overlays to ship command modules rather than loose
+  scripts, and skills to name the tools they use.
+
 ## [0.7.2] - 2026-10-03
 
 ### Added
@@ -1384,7 +1394,8 @@ Patch release: the PATH/POSIX-conversion fix above (the only change since 0.3.0)
   affected module sources (`dotagents.cli`, `duho.presets`) to extracted temp files
   before dispatch; a no-op for a plain install.
 
-[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.7.2...HEAD
+[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.7.3...HEAD
+[0.7.3]: https://github.com/jose-pr/dotagents/compare/v0.7.2...v0.7.3
 [0.7.2]: https://github.com/jose-pr/dotagents/compare/v0.7.1...v0.7.2
 [0.7.1]: https://github.com/jose-pr/dotagents/compare/v0.7.0...v0.7.1
 [0.7.0]: https://github.com/jose-pr/dotagents/compare/v0.6.3...v0.7.0

{dotagents_cli-0.7.2 → dotagents_cli-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.7.2
+Version: 0.7.3
 Summary: The dotagents CLI: install and manage a portable ~/.agents config for AI coding agents
 Project-URL: Homepage, https://github.com/jose-pr/dotagents/
 Project-URL: Repository, https://github.com/jose-pr/dotagents

{dotagents_cli-0.7.2 → dotagents_cli-0.7.3}/docs/guide/authoring.md

@@ -149,7 +149,26 @@ parser cannot be built. The bundled `findings` and `launch` are ordinary command
 modules discovered from the package, and the private-sync overlay ships
 `link-project` / `sync-project` from its own `cmds/` the same way.
 
+**Prefer a command module to a loose script.** A script under `tools/` is something
+an agent has to find, quote and spawn. A command module is discovered, shows up in
+`dotagents --help`, and is served as an MCP tool with a typed schema when `dotagents`
+runs with `DOTAGENTS_MCP=stdio` (see
+[Commands → As tools for an agent](commands.md#as-tools-for-an-agent)). Write it to be
+a good tool:
+
+- the logic lives in the command class — `__call__` and its methods — not in one
+  function that `__call__` forwards every field to;
+- each field's help says what the value is, since it becomes the schema's description;
+- the output is short: one line for a change, the smallest useful part for a read,
+  `--json` for a program;
+- it never prompts, and a command that deletes or publishes needs an explicit flag.
+
 ## Skills
 
 Put `skills/<skill-name>/` directories in your overlay to publish shared skills into
 the scope on install. See [Overlays → Skills](overlays.md#skills).
+
+A skill that relies on commands says so, in its own text: which `dotagents` commands
+it uses, that they are available as MCP tools (`dotagents.<command>`) when the
+server is registered, and the command-line form to fall back to when it is not. An
+agent reading the skill should not have to discover either.

{dotagents_cli-0.7.2 → dotagents_cli-0.7.3}/docs/guide/commands.md

@@ -59,6 +59,38 @@ into `<store>/dotagents/cmds/` (create the dir — `init` does not) and it becom
 subcommand, no registration needed; see
 [Authoring → Custom commands](authoring.md#custom-commands).
 
+## As tools for an agent
+
+Every command above except `env`, and every discovered one, is also an **MCP tool**.
+Start `dotagents` with `DOTAGENTS_MCP=stdio` in its environment and it serves that
+command set over stdio instead of running a command:
+
+```sh
+DOTAGENTS_MCP=stdio dotagents        # register this as a stdio MCP server in your agent
+```
+
+- One tool per leaf command, named with dots: `dotagents.findings.add`,
+  `dotagents.overlays.list`, and for an overlay's commands `dotagents.<command>`.
+- A tool's input schema is generated from the command's fields; its result is what
+  the command prints.
+- The command set is discovered once, when the server starts, for the directory it
+  starts in. Restart it after installing an overlay or changing project.
+
+Use it for a command an agent calls many times in a session — a findings queue, a
+plan's progress, a lookup. A tool call skips the interpreter start-up and the
+command discovery that every `dotagents <command>` process pays, and its arguments
+are typed values, not strings quoted through a shell.
+
+`env` is not served: it prints resolved values, which can be secrets. Everything
+else is, including the commands that change the store (`init`, `overlays add`,
+`overlays remove`). Register the server only where the agent is meant to be able to
+run them.
+
+For a machine-readable description without a server, set `AGENT_HELP=1` and ask for
+`--help`: `dotagents findings --help` then prints one JSON document for that command
+tree. It is complete and long; a single subcommand's plain `--help` is shorter when
+that is all that is needed.
+
 ## init
 
 See [Install](install.md) for the full walkthrough. In brief:
@@ -501,13 +533,13 @@ There is no `dotagents audit`. The dotagents source repo has its own
 it is not a validator for an installed `~/.agents` and is deliberately not shipped
 in the package or the `.pyz`.
 
-### Personal pre-push scanning (not in this repo)
+### Pre-push scanning (an overlay's command)
 
-Scanning a repo for personal leaks before publishing it — machine paths, private
-plan names, `.agents/` refs, agent-session trailers in commit messages — enforces
-personal conventions rather than dotagents' own mechanism, so no such tool is
-shipped here. Keep one as a discovered command module in your own private
-`<scope>/dotagents/cmds/` and run it locally before a push.
+Scanning a repo for leaks before publishing it — machine paths, private plan names,
+`.agents/` refs, agent-session trailers in commit messages — enforces a convention
+rather than dotagents' own mechanism, so the package ships no such command. The
+opt-in `engineering` overlay does: `dotagents leak-check <repo>`. Its patterns for
+what is personal to you stay in a machine-local file, never in a repository.
 
 ## link-project / sync-project
 

{dotagents_cli-0.7.2 → dotagents_cli-0.7.3}/docs/guide/overlays.md

@@ -44,7 +44,7 @@ or `--repo <checkout>/overlays` for a local checkout of the branch.
 
 | Overlay | What it carries |
 | --- | --- |
-| `engineering` | One opinionated engineering process. `rules/ENGINEERING.md` — always-on discipline merged into `AGENTS.md` (commit shape, release-tag consent, benchmark-as-evidence, token discipline, draft follow-ups). `flows/` — `PLAN.md` (a strong model writes precise, autonomous plans), `EXEC.md` (a cheaper model executes them without re-deriving context), `REVIEW.md` (file-threaded multi-agent plan review), `REPO.md` (the repo standard); `kb/MODELS.md` (executor/model selection). `references/` — language-neutral repo-file templates (README, CHANGELOG, LICENSE, `.gitignore`, docs-index, the plan template). `tools/` — `summarize_run` (command → verdict) and `compare_bench` (diff benchmark JSONs). The language overlays require it. |
+| `engineering` | One opinionated engineering process. `rules/ENGINEERING.md` — always-on discipline merged into `AGENTS.md` (commit shape, release-tag consent, benchmark-as-evidence, token discipline, draft follow-ups). `flows/` — `PLAN.md` (a strong model writes precise, autonomous plans), `EXEC.md` (a cheaper model executes them without re-deriving context), `REVIEW.md` (file-threaded multi-agent plan review), `REPO.md` (the repo standard); `kb/MODELS.md` (executor/model selection). `references/` — language-neutral repo-file templates (README, CHANGELOG, LICENSE, `.gitignore`, docs-index, the plan template). `cmds/` — `plans`, `leak-check`, `eol`, `summarize-run` (command → verdict) and `compare-bench` (diff benchmark JSONs), each a `dotagents` command. The language overlays require it. |
 | `python`, `node`, `rust` | Per-language `kb/` conventions + manifest templates + CI workflow templates. |
 | `release` | A host-agnostic release helper: an agent-driven commit-plan loop plus tag/CI monitoring across GitHub (`gh`) and GitLab. |
 | `private-sync` | The one-private-repo, per-project `.agents` model (`kb/PRIVATE_SYNC.md` + cloud hooks) — see [Private sync](private-sync.md). |

{dotagents_cli-0.7.2 → dotagents_cli-0.7.3}/src/dotagents/AGENTS.md

@@ -44,6 +44,16 @@ and an error saying a command is required, and exits 2.
 | `about [--json]` | `dotagents-cli <version>`, then `<distribution> <version>` per bundled (`.pyz`) or installed package. |
 | `build-pyz [--out P] [--python SHEBANG] [--duho-version V] [--pathlib-next-version V] [--extras a,b]` | Build a zipapp from a source checkout; errors elsewhere. |
 
+**Every command but `env` is also an MCP tool.** With `DOTAGENTS_MCP=stdio` in its
+environment, `dotagents` serves the command set — built-in, bundled and discovered —
+over stdio instead of running one: a tool per leaf command, named with dots
+(`dotagents.findings.add`, `dotagents.overlays.list`), its input schema generated from
+the command's fields, its result the command's output. `env` is not served: it prints
+resolved, possibly secret values. The set is fixed when the server starts, for the
+scope it starts in. With `AGENT_HELP=1`, `--help` prints one
+JSON document (`duho/agent-help@1`) for the command tree it is asked about, in place
+of the human text.
+
 Scope flags: `-g` / `--global` selects the user store; `--agents-dir D` overrides the
 store the command resolves to (the project store for `init` / `overlays` / `findings`
 without `-g`, the user store otherwise). For `env`, `context` and `launch`, `-g` means

{dotagents_cli-0.7.2 → dotagents_cli-0.7.3}/src/dotagents/__init__.py

@@ -1,3 +1,3 @@
 """dotagents: installable CLI for the dotagents agent-config payload."""
 
-__version__ = "0.7.2"
+__version__ = "0.7.3"