Metadata-Version: 2.5
Name: plesty-hub-agents
Version: 0.1.1
Summary: Harness-agnostic agentic framework for developing and maintaining PLESTY hub modules.
Author-email: Yunshuang Yuan <yuanyunshuang@gmail.com>
License-Expression: LGPL-3.0-or-later
License-File: LICENSE
License-File: LICENSES/LGPL-3.0-or-later.txt
Requires-Python: >=3.12
Requires-Dist: packaging<27,>=24
Requires-Dist: pyyaml<7,>=6.0
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.2; extra == 'mcp'
Description-Content-Type: text/markdown

# plesty-hub-agents

Skills and agent roles for building PLESTY lab experiments and the hub modules behind them —
device drivers, analyzers and experiments — with the coding agent you already use.

Tell it which instruments you have and what you want to measure. It writes the device servers,
field-tests them on your hardware until they pass, builds the experiment, runs it with you on
the bench, and then improves it run by run — asking you before every step that touches the
hardware and before every new round.

## Install

### Claude Code — as a plugin (recommended)

```
/plugin marketplace add https://gitlab.com/plesty/ai/plesty-hub-agents.git
/plugin install plesty-hub-agents@plesty
```

The skills appear as `/plesty-hub-agents:hub-experiment`, `/plesty-hub-agents:hub-comply`, … and
the roles as subagents. `/plugin update` brings in each release. For the MCP tools
(`plesty check`, GitLab and PyPI look-ups) also install the CLI:

```bash
uv tool install "plesty-hub-agents[mcp] @ git+https://gitlab.com/plesty/ai/plesty-hub-agents"
hub-agents doctor        # uv, git, glab, Python — installs what it can, never with sudo
```

### Claude app (claude.ai, Claude Desktop) — as skills

1. **Turn on code execution** — skills need it. Open
   [claude.ai/settings/capabilities](https://claude.ai/settings/capabilities) and switch on
   **Code execution and file creation** (called **Create and edit files** in the newer layout).
2. **Make the zips** — one per skill, all at once:
   ```bash
   git clone --branch v0.1.1 https://gitlab.com/plesty/ai/plesty-hub-agents.git
   cd plesty-hub-agents/skills && for s in hub-*; do zip -qr "$s.zip" "$s"; done
   ```
3. **Upload them** at [claude.ai/customize/skills](https://claude.ai/customize/skills): **+** →
   **Create skill** → **Upload a skill** → a zip. **One skill per upload** — the app has no
   multi-skill upload, so repeat for each zip you want (`hub-experiment.zip` is enough to plan
   and analyse experiments).
4. **Switch each skill on** in the list, then start a chat: "use hub-experiment for a new
   experiment called pow-pl".

**For a whole team in one go** (Team or Enterprise plan): an organization owner can upload the
skills once under **Organization settings → Plugins & skills**, and they appear for every
member. The owner also enables **Code execution and file creation** and **Skills** there, on
the **Policy** tab — if [claude.ai/customize/skills](https://claude.ai/customize/skills) has no
upload option for you, ask the owner. Details in [Using the framework](docs/usage.md#claude-app-skills).

The menu labels follow Anthropic's [Use skills in Claude](https://support.claude.com/en/articles/12512180-use-skills-in-claude)
article; if they have moved again, that article has the current ones.

The app has no access to your lab network or your checkouts, so use it for the stages that are
conversation and analysis — requirements, the plan, reading a finished run and proposing the
next round. Building, field-testing and running happen in Claude Code (see
[the experiment guide](docs/experiment.md)).

### Codex CLI, Gemini CLI — through the CLI

```bash
hub-agents workspace init ~/plesty-hub    # one directory for all modules; projects every harness on PATH
cd ~/plesty-hub && codex                  # or gemini — or claude, if you do not use the plugin
```

## Build an experiment

```
/plesty-hub-agents:hub-experiment pow-pl
```

| Stage | What happens | You |
|---|---|---|
| 1 Requirements | Q&A: each device (model, role, bench, connection, manual, safety limits), then the experiment (plan, records, in-run decisions, success) | answer, confirm |
| 2 Plan | what each device module and the experiment need, what runs in parallel, the risks | approve |
| 3 Devices | one agent per device, in parallel; then the hardware set-up and a field-test loop — find the cause, fix, test again — until each device passes | connect the hardware, say when it is free to act |
| 4 Experiment | the experiment module, a dry run and a full run against the device simulators | review the MR |
| 5 Run | you run it from the bench console with the agent monitoring, or the agent runs it | pick one |
| 6 Refine | efficiency, parameters, in-run decisions, data quality, robustness — a proposal for the next round | approve each round |

The pipeline keeps its state in `.hub-agents/experiments/<slug>/`, so it resumes where it
stopped. That folder holds bench addresses and lab notes and is never committed.

## What ships

| Skill | Does |
|---|---|
| `hub-experiment` | instruments to a successful, improving experiment — the six stages above |
| `hub-module` | a new device module: architect → engineer → publisher |
| `hub-field-test` | configure a device's field test, or run it on the hardware |
| `hub-comply` | `plesty check` → triage → fix → repeat until every gate passes |
| `hub-develop` | branch off the right line → implement → comply → commit → MR |
| `hub-docs` | audit a module's `docs/` against its code and fix it |
| `hub-publish` | release merge, tag, CI, PyPI, merge back |
| `hub-workspace` | clone / status / update checkouts by name, path or group |

Roles `hub-architect` → `hub-engineer` → `hub-publisher` hand off through
`.hub-agents/handoff/*.md`. Branch guards stop an edit or a push on `main`, `exp` or a
`maintain/*` line. Skills are validated for plesty-lib `>=0.6.0,<0.7` and plesty-sdk
`>=0.5.0,<0.6`; a module pinned outside that range is told so.

## Documentation

- [Build an experiment](docs/experiment.md) — the pipeline, in Claude Code and in the Claude app
- [Using the framework](docs/usage.md) — install, workspace, every skill, the module pipeline, MCP, headless use
- [Architecture](docs/architecture.md) — how one set of skills serves every harness

## Develop

```bash
uv sync --all-extras
uv run pytest            # catalog, plugin manifests, contracts against the installed lib/sdk
uv run plesty check      # quantum, every gate
```

Changes land through a merge request into `exp`; `main` moves only by release.

## License

LGPL-3.0-or-later, see [LICENSE](LICENSE).
