Metadata-Version: 2.4
Name: my-fleet
Version: 0.1.0
Summary: Reusable agent-fleet machinery projected out of a production multi-harness agent workspace: skills, charters, policies, and the harness-sync engine that lands them in Claude, Codex, Gemini, Cursor, and friends.
License-Expression: MPL-2.0
Project-URL: Homepage, https://gitlab.com/doering-ai/libs/fleet
Project-URL: Source, https://gitlab.com/doering-ai/libs/fleet
Project-URL: Issues, https://gitlab.com/doering-ai/libs/fleet/-/issues
Project-URL: Documentation, https://my-fleet.readthedocs.io
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3.13
Classifier: Framework :: Pydantic :: 2
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.12.4
Requires-Dist: more-itertools>=10.7.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: httpx[http2]>=0.28
Requires-Dist: my-basis>=1.0
Provides-Extra: mcp
Requires-Dist: fastmcp>=3.4.0; extra == "mcp"
Provides-Extra: lm
Requires-Dist: dspy>=2.5.0; extra == "lm"
Dynamic: license-file

<!-- readme-header:begin -->

<div align="center">

<img src="assets/logo_512.png" alt="myFleet logo" width="180">

# myFleet: _Fleet Toolkit for Agentic Work_

<p align="center">
  <a href="https://gitlab.com/doering-ai/libs/fleet/-/pipelines"><img src="https://img.shields.io/gitlab/pipeline-status/doering-ai%2Flibs%2Ffleet?branch=main" alt="pipeline status"></a> <a href="LICENSE"><img src="https://img.shields.io/gitlab/license/doering-ai%2Flibs%2Ffleet" alt="license: MPL-2.0"></a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.13%2B-blue?logo=python&logoColor=white" alt="Python 3.13+"> <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="ruff"></a> <a href="https://github.com/facebook/pyrefly"><img src="https://img.shields.io/endpoint?url=https://pyrefly.org/badge.json" alt="pyrefly"></a>
</p>

</div>

<!-- readme-header:end -->

myFleet is a toolkit of agent-fleet machinery: agent skills, charters, and behavior policies from a working multi-agent setup, plus the harness-sync engine that projects them into eleven coding-agent checkouts — Claude, Codex, Gemini, Cursor, Factory droids, OpenCode, Kilo, Kimi, Antigravity, Vix, and ZCode. It is generalized from a production multi-agent workspace, where every piece is in daily use.

The problem it addresses is familiar to anyone running more than one agent harness: the same instructions, skills, and settings get maintained N times in N tools' private formats, and drift quietly. myFleet keeps one canonical copy of each artifact and treats every harness copy as generated. Policies are written as citable rule IDs (`- **ID** — proposition`) so a skill, charter, or review can reference a rule instead of restating it. Work lands through a review gate, not direct pushes. The content directories are data; the `fleet` package is the engine that moves the data.

## Repository tour

| Path                     | Contents                                                                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| [`skills/`](skills/)     | 46 agent skills in four families — lifecycle verbs (`000`–`111`), `build-*`, `use-*`, and craft. See [docs/skills.md](docs/skills.md) |
| [`agents/`](agents/)     | 11 agent charters, the shared base commitments, and a MANIFEST navigation snapshot. See [docs/agents.md](docs/agents.md)              |
| [`policies/`](policies/) | 29 rule documents plus the `permissions.yaml` shorthand, all in a stable ID grammar. See [docs/policies.md](docs/policies.md)         |
| [`settings/`](settings/) | Shared configuration fragments, including the canonical MCP registry ([`mcp.jsonc`](settings/mcp.jsonc))                              |
| [`fleet/`](fleet/)       | The Python package: sync engine, pollers, session analytics, and CLIs                                                                 |
| [`docs/`](docs/)         | The documentation hub — [docs/index.md](docs/index.md)                                                                                |

## Quickstart

Python 3.13+ is the only runtime requirement. The engine is **checkout-first by design**: the sync engine projects this repository's `skills/`, `policies/`, and `agents/` trees into your harnesses, so it runs from a clone rather than a site-packages install. (A PyPI release of the wheel is planned; the memory and analytics CLIs are the install-independent subset.)

```sh
git clone https://gitlab.com/doering-ai/libs/fleet.git && cd fleet
uv sync --all-extras
uv run sync-agents -n     # read-only preview of every projection
uv run sync-agents --check  # report drift between sources and generated consumers
uv run sync-policies -n   # preview the permissions projection
```

Run the same commands without the `uv run` prefix once the environment is active. Applying is idempotent: symlinks already pointing at the right target are left alone, hook registrations de-duplicate, and unrelated keys in harness settings survive untouched.

## The `fleet` package

Six console scripts cover the engine's jobs; two background pollers keep shared state fresh.

| CLI                  | Purpose                                                                                                                                 |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `sync-agents`        | Project instructions, skills, charters, hooks, and MCP config into the supported harnesses — [docs/sync-agents.md](docs/sync-agents.md) |
| `sync-policies`      | Expand `policies/permissions.yaml` into a harness settings permission list                                                              |
| `agent-memory-index` | Concurrency-safe maintenance of per-agent `MEMORY.md` indexes — [docs/memory.md](docs/memory.md)                                        |
| `fleet-memory-mcp`   | FastMCP stdio server exposing the memory store to stateless agents                                                                      |
| `agentlog`           | Session-lifecycle analytics across harness surfaces — [docs/agentlog.md](docs/agentlog.md)                                              |
| `ai-home`            | Resolve `$AI_HOME` (default `~/ai`), the agent-owned working-state home                                                                 |

The pollers are plain scripts meant to run under a systemd user timer: the bulletin poller snapshots and cross-checks the shared agent bulletin ([docs/bulletin.md](docs/bulletin.md)), and the memory poller commits new agent-memory files to the default branch ([docs/memory.md](docs/memory.md)).

## Design notes

- **Data is not code.** `skills/`, `agents/`, `policies/`, and `settings/` are plain files a human can read and diff; the package only moves and renders them. Generated consumers are never sources.
- **Dependency discipline.** The ported modules stay stdlib-plus-pydantic by design, so they run inside externally-managed environments. Shared utilities come from [my-basis](https://pypi.org/project/my-basis/) where it clearly helps, and nothing depends on a private package.
- **Preview, then idempotent apply.** Every projection has a dry-run; applying twice changes nothing.
- **Hooks are boring.** Hook scripts are pure-stdlib programs that speak JSON over stdio; only the per-harness registration format differs.
- **Rules are citable.** Policies use stable ID anchors with nested scope, so agents can be pointed at a rule instead of a wall of prose.

## Roadmap

- **`agent-worktree`** — per-agent git worktree isolation with a review-gated merge path. The [policies](policies/worktrees.md) describe the workflow today; the CLI has not been generalized yet.
- **`agentviz`** — interactive dashboards over the `agentlog` data.
- **Tracker sync** — reconcile a local task mirror with a hosted tracker; the `use-plane` skill documents the working method.

## Provenance and sanitization

The contents are generalized from a production multi-agent workspace, and publication means the private provenance stays out. That is enforced, not promised: [`scripts/check_sanitized.py`](scripts/check_sanitized.py) scans every tracked file in CI for known private patterns — names, hosts, home paths, vault references, ID fragments — and fails the pipeline on any genuine hit. The carve-outs are few and documented in the script: forge URLs in this repository's own namespace, secret-store product documentation in the `auth` skill, and the engine's own harness identifiers.

## Contributing and license

GitLab is the development forge; report issues and propose changes at [the GitLab project](https://gitlab.com/doering-ai/libs/fleet). Changes pass the same sanitizer and pipeline as everything else.

Licensed under [MPL-2.0](LICENSE).
