Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ If this returns a version number, the CLI is available. If it errors, proceed wi

### Validate a connector config
```bash
npx @stackone/cli validate src/configs/<provider>/<provider>.connector.s1.yaml
npx @stackone/cli validate connectors/<provider>/<provider>.connector.s1.yaml
```
Checks YAML structure, required fields, and action definitions. Returns validation errors with line numbers.

Expand All @@ -28,7 +28,7 @@ Returns a list of provider names StackOne has indexed. Use to check if a connect
```bash
npx @stackone/cli pull <provider-name>
```
Downloads the connector config to `src/configs/<provider>/`. Creates the folder and YAML files if they don't exist. Use as a starting point.
Downloads the connector config to `connectors/<provider>/`. Creates the folder and YAML files if they don't exist. Use as a starting point.

### Test an action
```bash
Expand All @@ -45,7 +45,7 @@ npx @stackone/cli test <provider> <action-name> --debug
```bash
npx @stackone/cli scaffold <provider-name>
```
Creates `src/configs/<provider>/` with a starter `<provider>.connector.s1.yaml`. Does NOT pull from StackOne's index — creates a blank template.
Creates `connectors/<provider>/` with a starter `<provider>.connector.s1.yaml`. Does NOT pull from StackOne's index — creates a blank template.

## Environment Setup

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Used by `map-fields` and `validate-connector` sub-skills.
## File Structure

```
src/configs/<provider>/
connectors/<provider>/
├── <provider>.connector.s1.yaml # Main connector (auth, base config)
└── <provider>.<resource>.s1.partial.yaml # Actions for each resource
```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Use any data from `get_provider_actions` or the builder's API docs.

## Step 2: Write partial YAML files

Create `src/configs/{{provider}}/{{provider}}.{{resource}}.s1.partial.yaml` for each resource.
Create `connectors/{{provider}}/{{provider}}.{{resource}}.s1.partial.yaml` for each resource.

### list action
```yaml
Expand Down Expand Up @@ -175,7 +175,7 @@ Create `src/configs/{{provider}}/{{provider}}.{{resource}}.s1.partial.yaml` for

## Step 3: Update main connector YAML with $refs

Read `src/configs/{{provider}}/{{provider}}.connector.s1.yaml` and add a `$ref` per partial under `actions`:
Read `connectors/{{provider}}/{{provider}}.connector.s1.yaml` and add a `$ref` per partial under `actions`:

```yaml
actions:
Expand All @@ -188,8 +188,8 @@ actions:
## Step 4: Review with builder

> "Config written:
> - `src/configs/{{provider}}/{{provider}}.connector.s1.yaml` (updated)
> - `src/configs/{{provider}}/{{provider}}.employees.s1.partial.yaml`
> - `connectors/{{provider}}/{{provider}}.connector.s1.yaml` (updated)
> - `connectors/{{provider}}/{{provider}}.employees.s1.partial.yaml`
> - ...
>
> Do the endpoint URLs and HTTP methods look right? Any actions need adjusting?"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ Ask for the specific values needed:

## Step 3: Write auth block into connector YAML

Read `src/configs/{{provider}}/{{provider}}.connector.s1.yaml`.
Read `connectors/{{provider}}/{{provider}}.connector.s1.yaml`.

Replace the `authentication: {}` placeholder with the correct pattern from `auth-patterns.md`.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -67,15 +67,15 @@ Use `-x` for full-line matching to avoid false positives from substring or hyphe
```bash
npx @stackone/cli pull {{provider}}
```
Verify `src/configs/{{provider}}/` was created. Save `connector_exists: true`.
Verify `connectors/{{provider}}/` was created. Save `connector_exists: true`.

Note: A provider may have indexed actions (from Step 2) but no pullable connector config. Always check the CLI list before attempting `pull`.

**If not in index or scaffolding fresh:**
```bash
npx @stackone/cli scaffold {{provider}}
```
Or if CLI unavailable, create `src/configs/{{provider}}/{{provider}}.connector.s1.yaml` manually:
Or if CLI unavailable, create `connectors/{{provider}}/{{provider}}.connector.s1.yaml` manually:
```yaml
name: {{provider}}
version: "1.0"
Expand All @@ -85,13 +85,13 @@ actions: []
```
Save `connector_exists: false`.

Save `connector_path: "src/configs/{{provider}}"` to session.
Save `connector_path: "connectors/{{provider}}"` to session.

---

## Handoff

> "Setup complete. ✓ Connector at `src/configs/{{provider}}/`
> "Setup complete. ✓ Connector at `connectors/{{provider}}/`
>
> Next: configure authentication.
> Run `/configure-auth` to continue."
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ Execute `/configure-auth` logic. Saves: `auth_type`. Writes auth block to connec
Execute `/discover-actions` logic. Saves: `discovery_mode`, `action_scope`, `use_case`.

### Step 4 — Build Config
Execute `/build-config` logic. Writes action YAML to `src/configs/{{provider}}/`.
Execute `/build-config` logic. Writes action YAML to `connectors/{{provider}}/`.

### Step 5 — Validate
Execute `/validate-connector` logic. Saves: `validated: true`.
Expand All @@ -69,7 +69,7 @@ Execute `/test-connector` logic. Saves: `tested: true`, `test_artifacts`, `compl
{
"provider": "workday",
"provider_key": "workday",
"connector_path": "src/configs/workday",
"connector_path": "connectors/workday",
"cli_available": true,
"connector_exists": false,
"auth_type": "oauth2",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,14 @@ Reference `${CLAUDE_PLUGIN_ROOT}/references/cli-commands.md` for CLI usage and e

Run:
```bash
npx @stackone/cli validate src/configs/{{provider}}/{{provider}}.connector.s1.yaml
npx @stackone/cli validate connectors/{{provider}}/{{provider}}.connector.s1.yaml
```

Capture the full output. Proceed to Step 2 to interpret any errors.

### If `cli_available: false`

The CLI is not available. Run the manual checklist below against every partial file in `src/configs/{{provider}}/`.
The CLI is not available. Run the manual checklist below against every partial file in `connectors/{{provider}}/`.

**Manual checklist for generic connectors:**

Expand All @@ -57,7 +57,7 @@ Work through each action across all `{{provider}}.{{resource}}.s1.partial.yaml`

9. **`delete` actions use DELETE** — Actions named `delete_*` must have `method: delete` in the request step.

10. **All `$ref` paths in main connector file exist** — Read `src/configs/{{provider}}/{{provider}}.connector.s1.yaml`. For every `$ref` entry under `actions`, verify the referenced partial file exists on disk at the given relative path.
10. **All `$ref` paths in main connector file exist** — Read `connectors/{{provider}}/{{provider}}.connector.s1.yaml`. For every `$ref` entry under `actions`, verify the referenced partial file exists on disk at the given relative path.

11. **No tabs — 2-space indentation only** — Scan each YAML file for tab characters (`\t`). YAML does not allow tabs. All indentation must use spaces (2 per level).

Expand Down Expand Up @@ -120,7 +120,7 @@ actions:
- $ref: "./{{provider}}.employees.s1.partial.yaml"
```

The file `src/configs/{{provider}}/{{provider}}.employees.s1.partial.yaml` must exist. Check for typos in the provider name, resource name, or `.s1.partial.yaml` suffix.
The file `connectors/{{provider}}/{{provider}}.employees.s1.partial.yaml` must exist. Check for typos in the provider name, resource name, or `.s1.partial.yaml` suffix.

---

Expand Down Expand Up @@ -196,7 +196,7 @@ Once validation passes with no errors:
> "Validation passed. ✓
>
> **`{{provider}}` connector summary:**
> - Config: `src/configs/{{provider}}/{{provider}}.connector.s1.yaml`
> - Config: `connectors/{{provider}}/{{provider}}.connector.s1.yaml`
> - Partial files: {{list each partial file}}
> - Actions validated: {{N}} ({{list action names}})
> - All actions use `actionType: custom`
Expand Down
4 changes: 2 additions & 2 deletions .claude/plugins/stackone-unified-builder/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ If a `.connector-build-session.json` exists, the wizard will offer to resume fro

## What it builds

A set of YAML configuration files in `src/configs/<provider>/` that expose provider API data through StackOne's unified API. Supports both StackOne built-in schemas (HRIS, ATS, CRM, etc.) and custom schemas you define.
A set of YAML configuration files in `connectors/<provider>/` that expose provider API data through StackOne's unified API. Supports both StackOne built-in schemas (HRIS, ATS, CRM, etc.) and custom schemas you define.

## Schema options

Expand All @@ -53,7 +53,7 @@ A set of YAML configuration files in `src/configs/<provider>/` that expose provi

## Requirements

- `connectors-template` project structure (`src/configs/` directory)
- `connectors-template` project structure (`connectors/` directory)
- Node.js — for the StackOne CLI (optional but recommended)
- Provider API credentials in `.env`

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ If this returns a version number, the CLI is available. If it errors, proceed wi

### Validate a connector config
```bash
npx @stackone/cli validate src/configs/<provider>/<provider>.connector.s1.yaml
npx @stackone/cli validate connectors/<provider>/<provider>.connector.s1.yaml
```
Checks YAML structure, required fields, and action definitions. Returns validation errors with line numbers.

Expand All @@ -28,7 +28,7 @@ Returns a list of provider names StackOne has indexed. Use to check if a connect
```bash
npx @stackone/cli pull <provider-name>
```
Downloads the connector config to `src/configs/<provider>/`. Creates the folder and YAML files if they don't exist. Use as a starting point.
Downloads the connector config to `connectors/<provider>/`. Creates the folder and YAML files if they don't exist. Use as a starting point.

### Test an action
```bash
Expand All @@ -45,7 +45,7 @@ npx @stackone/cli test <provider> <action-name> --debug
```bash
npx @stackone/cli scaffold <provider-name>
```
Creates `src/configs/<provider>/` with a starter `<provider>.connector.s1.yaml`. Does NOT pull from StackOne's index — creates a blank template.
Creates `connectors/<provider>/` with a starter `<provider>.connector.s1.yaml`. Does NOT pull from StackOne's index — creates a blank template.

## Environment Setup

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Used by `map-fields` and `validate-connector` sub-skills.
## File Structure

```
src/configs/<provider>/
connectors/<provider>/
├── <provider>.connector.s1.yaml # Main connector (auth, base config)
└── <provider>.<resource>.s1.partial.yaml # Actions for each resource
```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -85,11 +85,11 @@ Run:
npx @stackone/cli pull {{provider}}
```

Verify `src/configs/{{provider}}/` was created and contains at least one `.yaml` file.
Verify `connectors/{{provider}}/` was created and contains at least one `.yaml` file.

List the files found and confirm:
> "Pulled connector config:
> - `src/configs/{{provider}}/{{provider}}.connector.s1.yaml`
> - `connectors/{{provider}}/{{provider}}.connector.s1.yaml`
> - ..."
>
> "This is a starting point — we'll add unified actions on top. Does the folder look right?"
Expand All @@ -98,7 +98,7 @@ Save to session:
```json
{
"connector_exists": true,
"connector_path": "src/configs/{{provider}}"
"connector_path": "connectors/{{provider}}"
}
```

Expand All @@ -114,7 +114,7 @@ Ask the builder about authentication:
> **C) Basic Auth** — username and password
> **D) Something else** — I'll help you figure it out"

Read `${CLAUDE_PLUGIN_ROOT}/references/connector-patterns.md` and use the matching pattern to create `src/configs/{{provider}}/{{provider}}.connector.s1.yaml`.
Read `${CLAUDE_PLUGIN_ROOT}/references/connector-patterns.md` and use the matching pattern to create `connectors/{{provider}}/{{provider}}.connector.s1.yaml`.

**If CLI is available, try scaffolding first:**
```bash
Expand All @@ -126,7 +126,7 @@ Then open the generated file and update the `authentication` block to match the
**If CLI is not available:** Write the starter YAML directly using the matching pattern from `connector-patterns.md`.

After creating the file, tell the builder:
> "Created starter connector at `src/configs/{{provider}}/{{provider}}.connector.s1.yaml`.
> "Created starter connector at `connectors/{{provider}}/{{provider}}.connector.s1.yaml`.
>
> Before testing, add your credentials to `.env`:
> ```
Expand All @@ -139,7 +139,7 @@ Save to session:
```json
{
"connector_exists": false,
"connector_path": "src/configs/{{provider}}",
"connector_path": "connectors/{{provider}}",
"auth_type": "{{auth_type}}"
}
```
Expand All @@ -149,7 +149,7 @@ Save to session:
## Handoff

After the connector is set up:
> "Connector is ready at `src/configs/{{provider}}/`. ✓
> "Connector is ready at `connectors/{{provider}}/`. ✓
>
> **CLI available:** {{cli_available}}
> **Connector was pre-existing:** {{connector_exists}}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ When all fields for a resource are mapped, show the complete list and ask:
## Step 3: Write the partial YAML file

For each resource, create or update:
`src/configs/{{provider}}/{{provider}}.{{resource}}.s1.partial.yaml`
`connectors/{{provider}}/{{provider}}.{{resource}}.s1.partial.yaml`

Use the unified action pattern from `connector-patterns.md`. For each action in scope:

Expand Down Expand Up @@ -130,8 +130,8 @@ After all resources are mapped and partials are written:
> "Field mapping complete. ✓
>
> Files written:
> - `src/configs/{{provider}}/{{provider}}.connector.s1.yaml` (updated with $refs)
> - `src/configs/{{provider}}/{{provider}}.employees.s1.partial.yaml`
> - `connectors/{{provider}}/{{provider}}.connector.s1.yaml` (updated with $refs)
> - `connectors/{{provider}}/{{provider}}.employees.s1.partial.yaml`
> - ...
>
> Next step: validate the YAML configuration.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ Execute the full `/scope-actions` skill logic.

Execute the full `/map-fields` skill logic.

**Outcome:** Partial YAML files written to `src/configs/{{provider}}/`
**Outcome:** Partial YAML files written to `connectors/{{provider}}/`

---

Expand Down Expand Up @@ -123,7 +123,7 @@ Execute the full `/test-connector` skill logic.
"resources": ["employees", "time_off"],
"cli_available": true,
"connector_exists": false,
"connector_path": "src/configs/bamboohr",
"connector_path": "connectors/bamboohr",
"auth_type": "api_key",
"action_scope": {
"employees": ["list", "get"],
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Ask before running anything:
> {{PROVIDER_CREDENTIAL_NAME}}=your_value_here
> ```
>
> The exact variable name is in `src/configs/{{provider}}/{{provider}}.connector.s1.yaml` — look in the `authentication` block for the `args` key names."
> The exact variable name is in `connectors/{{provider}}/{{provider}}.connector.s1.yaml` — look in the `authentication` block for the `args` key names."

Wait for confirmation before proceeding.

Expand Down Expand Up @@ -133,7 +133,7 @@ When all actions pass:
> | `{{resource2}}` | {{actions2}} | ✓ |
>
> **Next steps:**
> 1. Commit your connector: `git add src/configs/{{provider}}/ && git commit -m 'feat: add {{provider}} unified connector'`
> 1. Commit your connector: `git add connectors/{{provider}}/ && git commit -m 'feat: add {{provider}} unified connector'`
> 2. If you'd like StackOne to index this connector, open a pull request to the connectors repository.
> 3. Test end-to-end with a real integration account."

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Step 5 of the unified connector build process.
## Session File

Read `.connector-build-session.json`. Confirm:
> "Validating connector at `src/configs/{{provider}}/`"
> "Validating connector at `connectors/{{provider}}/`"

If `connector_path` is missing:
> "No connector path in session. Run `/check-connector` first."
Expand All @@ -24,12 +24,12 @@ Read `${CLAUDE_PLUGIN_ROOT}/references/cli-commands.md` for the error table.

**If `cli_available` is true:**
```bash
npx @stackone/cli validate src/configs/{{provider}}/{{provider}}.connector.s1.yaml
npx @stackone/cli validate connectors/{{provider}}/{{provider}}.connector.s1.yaml
```

**If `cli_available` is false (manual review):**

Read each `.yaml` and `.partial.yaml` file in `src/configs/{{provider}}/` and check:
Read each `.yaml` and `.partial.yaml` file in `connectors/{{provider}}/` and check:
- All unified actions have `schemaType: unified`
- All unified actions have `entrypointUrl` and `entrypointHttpMethod`
- All unified actions have a `fieldConfigs` array
Expand Down Expand Up @@ -97,7 +97,7 @@ When validation passes (or manual review finds no issues):
> - Provider: `{{provider}}`
> - Resources: {{resources}}
> - Actions: {{action_scope}}
> - Config path: `src/configs/{{provider}}/`"
> - Config path: `connectors/{{provider}}/`"

Save `"validated": true` to session.

Expand Down
Loading
Loading