Metadata-Version: 2.5
Name: cuga-harness-kit
Version: 0.2.0
Summary: Scaffolds Claude Code / Cursor / Codex skills that teach coding agents to build with the cuga framework
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# cuga-harness-kit

Skills that teach Claude Code, Cursor, Codex, and Bob how to install, launch, and build with [cuga](https://github.com/cuga-project/cuga-agent) — the open-source generalist agent framework.

## Assistant quickstart

Paste this into Claude Code, Cursor, Codex, or Bob from the project folder you want to set up:

```text
Run `uv tool install --upgrade cuga-harness-kit`, then `cuga-harness-kit init` in this folder. Read and follow the full `using-cuga` skill.
```

This prompt installs the latest published release from PyPI.

The assistant will install this kit, scaffold the cuga guidance files, then follow `using-cuga`:

1. Inspect the existing project and reuse any established provider, execution mode, and successful checks.
2. Configure your LLM provider and verify a model request. Install CUGA for a local SDK app or local server when needed; use existing server-side configuration for a remote managed-server client.
3. Explain what you want to build and choose SDK embedding (usually your own app/UI) or a managed CUGA server (Manage UI, draft/publish config, HTTP clients). A custom UI can use either path.
4. Ask *"help me build a cuga tool"* or *"how do I add a policy"* when you're ready to build.

## Manual install

No git clone, no marketplace install:

```bash
uv tool install cuga-harness-kit
(if update: uv pip install -e . --reinstall-package cuga-harness-kit)
cuga-harness-kit init
```

If you're installing inside an already-active virtualenv instead of as a CLI tool, use `uv pip install cuga-harness-kit`.

Run `init` from an empty new project you're starting from scratch, or from inside an existing cuga checkout — either way it writes the same skill set into the current directory:

- `.claude/skills/<name>/SKILL.md` — auto-discovered by Claude Code.
- `.cursor/skills/<skill-name>/SKILL.md` — native Cursor skills; directory names match each skill's frontmatter `name` (for example `cuga-build-agent` or `using-cuga`).
- `AGENTS.md` — read by Codex. Re-running `init` only touches the managed block, so it won't clobber the rest of the file.
- `.bob/skills/<name>/SKILL.md` — auto-discovered by IBM Bob.
- `docs/cuga-env-api-keys.md` — local reference for `.env` API-key setup.

## What's included

| Skill | Teaches |
|---|---|
| `using-cuga` | New-build entry point: verify LLM configuration, understand the goal, choose SDK or managed server with the user. |
| `getting-started` | Routes focused requests to the appropriate builder skill. |
| `install-and-launch` | `uv init`, `uv add cuga`, `.env` API keys, `uv run cuga start <mode>`. |
| `build-agent` | Embedded single-agent `CugaAgent` SDK basics. |
| `build-supervisor` | SDK and managed multi-agent teams, specialist ID references, delegation, draft/publish checks and supervisor demos. |
| `managed-server` | Manage UI/HTTP draft → test → publish config; production invocation. |
| `build-cuga-skill` | Authoring cuga's own **runtime** skills — not the same as the IDE-assistant skills in this repo. |
| `build-tool` | Registering a LangChain / OpenAPI / MCP tool. |
| `author-policy` | Intent guards, playbooks, tool approval/guides, output formatters. |
| `knowledge-rag` | Document ingestion/search. |
| `debug-trajectory` | `cuga viz`, `cuga doctor`, common failure patterns. |

Each is authored once as a `SKILL.md` under `src/cuga_harness_kit/builder-skills/`, then used verbatim for Claude, Cursor and Bob or rendered into Codex `AGENTS.md` sections at `init` time.

## CLI

```bash
cuga-harness-kit init [--targets claude,cursor,codex,bob] [--force] [--dry-run]
cuga-harness-kit update   # alias for `init --force`
```

- `--targets` — comma-separated subset of `claude`, `cursor`, `codex`, `bob` (default: all four).
- `--force` — overwrite scaffolded files that already exist and differ (default: skip and report).
- `--dry-run` — print what would be written without touching disk.

## Migration pipeline (optional, claude/bob only)

Besides the guidance skills above, this kit can also scaffold **cuga-migrator** — a separate tool
that converts an *existing* agent system into a cuga SDK implementation, via a 5-stage pipeline
(analyst → implementer → test_writer → evaluator → debugger). It's opt-in and exclusive: it
replaces the guidance skills for that run rather than adding to them.

```bash
cuga-harness-kit init --targets claude --migration   # or --targets bob
```

This scaffolds the migration skills/agents, launch scripts, `cuga-templates/`, and
`migration_from/`/`migration_to/`, then clones the [cuga SDK](https://github.com/cuga-project/cuga-agent)
for the pipeline to reference. Once scaffolded, three more subcommands become available, grouped
under `migrate`:

```bash
cuga-harness-kit migrate source_sync <source-name>
cuga-harness-kit migrate cuga_sync
cuga-harness-kit migrate run <source-name> <target-name>
```

You can also just ask Claude Code / Bob directly, in natural language. See the scaffolded kit's
own `README.md` for the full walkthrough. Useful flags: `--skip-sdk` (don't clone the SDK),
`--cuga-ref <branch-or-tag>` (pin a version).

## Updating

New releases of `cuga-harness-kit` ship improved skill content. To pick it up in a project that already ran `init`:

```bash
uv tool upgrade cuga-harness-kit
cuga-harness-kit update
```

`update` overwrites scaffolded files unconditionally — if you hand-edited one to customize it, `update` will clobber that edit (there's no diff/merge, except for `AGENTS.md`'s managed block). Copy customizations out first if you want to keep them.

### Cursor rules to skills

Starting with 0.2.0, the Cursor target writes native skills instead of `.mdc` rules. To migrate an existing project after upgrading the package:

```bash
cuga-harness-kit init --targets cursor
```

After each native skill is installed, byte-identical generated `.cursor/rules/cuga-<name>.mdc` files are removed. Older or edited rules (including newline-only differences) are moved to inactive `.mdc.bak` files (or `.mdc.bak.1`, etc. when a backup already exists); the CLI reports their paths so you can transfer customizations into the new skills. Unrelated rules are left alone. Legacy rules reached through a symlinked file, `.cursor`, or `rules` directory are retained and reported for manual migration.

`init` preserves an existing native skill that differs, and leaves its legacy rule active until you resolve the conflict. `update --targets cursor` replaces differing native skills as usual. Use `init --targets cursor --dry-run` to preview writes, removals and backups without changing files.

## cuga project setup

When the generated skills help you install cuga in an app, they default to a `uv` project so dependencies are captured in `pyproject.toml`:

```bash
uv init my-cuga-app
cd my-cuga-app
uv add cuga
```

The SDK configures an agent in your Python process. The managed server reads per-agent draft and published versions from its config store. SDK tools/policies and `.cuga/` files do not automatically update managed config; use the managed-server skill for that workflow.

For API keys and provider settings, see [`docs/env-api-keys.md`](docs/env-api-keys.md).

## Development

```bash
uv sync
uv run pytest
```

For the runtime-backed builder checks and their coverage limits, see [builder validation](docs/builder-validation.md).
