# @stackone/agent-harness

StackOne's connector-building plugin for Claude Code, plus helpers to locate it and list its skills.

The plugin lives in `plugin/`: the gated Research → Build → Validate flow, with its commands, hooks, skills and the connector guide. This package ships it so the StackOne CLI can install it into a project.

## Using it

You don't install this package yourself. `@stackone/cli` depends on it and copies the plugin into your project:

```bash
stackone agent setup --local   # auth, .mcp.json, skills into .claude/, guide into CLAUDE.md
stackone agent sync            # refresh them after upgrading the CLI
claude
```

## API

Four helpers, used by `stackone agent sync` and `stackone agent skills`:

| Function                   | Returns                                                  |
| -------------------------- | -------------------------------------------------------- |
| `getBundledPluginPath()`   | Absolute path to the bundled `plugin/` directory         |
| `getBundledSkillsPath()`   | Absolute path to `plugin/skills/`                        |
| `getAvailableSkillNames()` | Names of the bundled skills                              |
| `getSkillsForMode(mode)`   | Skills recommended for `build`, `test` or `research`     |

## Documentation

| Guide                                               | Description                                            |
| --------------------------------------------------- | ------------------------------------------------------ |
| [Connector Plugin](plugin/README.md)                | The gated Research → Build → Validate Claude Code plugin in `plugin/`: commands, gates, run state, and how to run it |
| [Adding Skills](docs/01-skills.md)                  | Create a skill and test it in Claude Code              |
| [Plugin Development Lifecycle](plugin/docs/maintenance/development-lifecycle.md) | How a change to the plugin moves from first edit to a connector builder: verify, PR, benchmark, review, merge, delivery |
| [Benchmark PR Check](docs/02-benchmark-pr-check.md) | Label-gated PR check that benchmarks skill changes against main and posts a comparison comment (cost, per-prompt scores, min/max across runs) |
| [Falcon Knowledge Sync](docs/03-falcon-knowledge-sync.md) | Scheduled workflow that keeps the plugin's skills and connector guide in step with the connect SDK, and how to review its rolling PR |

## Bundled Skills

Claude Code invokes these when a task matches. The mode column is what `stackone agent skills --mode` recommends; it doesn't restrict loading.

| Skill                  | Mode            | Purpose                                                          |
| ---------------------- | --------------- | ---------------------------------------------------------------- |
| `connector-flow`       |                 | Route any connector request into Research → Build → Validate     |
| `research-provider`    | build, research | Phase 1: research the provider's API and authentication          |
| `build-connector`      | build           | Phase 2: author the connector YAML                               |
| `validate-config`      | build           | Phase 3: validate the connector configuration                    |
| `discover-actions`     | build, research | Discover a provider's API actions                                |
| `version-validation`   | build           | Validate API versions for discovered actions                     |
| `connector-patterns`   |                 | Reference for Falcon YAML patterns drawn from shipped connectors |
| `improve-descriptions` |                 | Improve a connector's action descriptions                        |
| `test-connector`       | test            | Test a connector's actions                                       |
| `test-mcp-connector`   | test            | Test a connector over MCP, only when asked for explicitly        |
| `scramble-credentials` | test            | Scramble credentials before they're stored or committed          |

See [Adding Skills](docs/01-skills.md) for creating your own.

## Development

This repo uses [pnpm](https://pnpm.io). The pnpm version is pinned in `package.json` under `packageManager` (Corepack picks it up automatically), and the Node.js version is pinned under `devEngines.runtime` in `package.json` (not `.npmrc`).

pnpm itself needs an existing Node.js to run (unless you installed it via the [standalone installer](https://pnpm.io/installation#using-a-standalone-script)). Once running, pnpm downloads the pinned Node.js version on demand and uses it for `pnpm run` scripts regardless of which Node.js is on your system.

```bash
corepack enable                   # picks up pnpm@<version> from packageManager
pnpm install --frozen-lockfile    # downloads the pinned Node.js on first run
pnpm node --version               # should print the version from devEngines.runtime
```

Use the pnpm version from `packageManager`. Older pnpm releases ran the strict `engines` check *before* downloading the pinned Node.js ([pnpm/pnpm#10033](https://github.com/pnpm/pnpm/issues/10033)), so an unpinned pnpm can fail with `ERR_PNPM_UNSUPPORTED_ENGINE` instead of fetching the right Node.js.

```bash
# Build
pnpm build

# Watch mode
pnpm start

# Test
pnpm test

# Lint
pnpm lint
```

## License

UNLICENSED