# Extend DevOps API Reuse Mechanism

This document defines how `dedicated-cloud-toolkit` reuses `devops-api` in a
consistent, runtime-safe way.

## Concept Model

- **Owner Skill**: `dedicated-cloud-toolkit` (owns intent routing and final behavior)
- **Provider Skill**: `devops-api` (provides transport conventions and script usage)
- **Reuse Mode**: `transport-only`

## When to Use This Mechanism

Use this mechanism when a toolkit subskill needs OPS backend API access and the
existing `devops-api` transport model is sufficient.

## Allowed Reuse Surface

Toolkit subskills may reuse these parts from `devops-api`:

- `Environments` section in `devops-api/SKILL.md`.
- `DevOps API Access` section in `devops-api/SKILL.md`.
- HTTP transport script path declared by provider skill (`scripts/devops_http.sh`).
- Shared request argument semantics and environment conventions.

## Forbidden Behavior

When using this mechanism, do not:

1. Delegate routing ownership to `devops-api`.
2. Cascade into `devops-api` sub-skill discovery for toolkit-owned flows.
3. Assume a fixed working directory when resolving provider files.
4. **NEVER** search beyond the expected provider path with `find`, recursive
   `glob`, or any broader filesystem scan. If the provider file is not found
   at the expected location, **MUST stop** and report the error to the user.

## Provider Resolution

Resolve provider data from the runtime-installed skill tree.

### Directory Structure

The skill tree follows this layout:

```
<skill-home>/
  dedicated-cloud-toolkit/   ← owner skill root
    SKILL.md
    mechanisms/extend-devops-api.md
    get-cluster-cr/SUBSKILL.md
  devops-api/                ← provider skill root
    SKILL.md
    scripts/devops_http.sh
```

`<skill-home>` is the parent directory of the owner skill root
(i.e., one level above `dedicated-cloud-toolkit/`).

### Concrete Path Resolution

Given the base directory from which `dedicated-cloud-toolkit/SKILL.md`
was loaded (e.g. `/Users/shaw/.config/opencode/skills/dedicated-cloud-toolkit/`),
derive the provider paths as follows:

1. **Provider skill root**: replace the trailing `dedicated-cloud-toolkit/`
   with `devops-api/` in the base directory path.
   Example: `/Users/shaw/.config/opencode/skills/devops-api/`

2. **Provider SKILL.md**: `<provider-skill-root>/SKILL.md`
   Example: `/Users/shaw/.config/opencode/skills/devops-api/SKILL.md`

3. **Provider transport script**: `<provider-skill-root>/scripts/devops_http.sh`
   Example: `/Users/shaw/.config/opencode/skills/devops-api/scripts/devops_http.sh`

After resolving paths, **you MUST read `SKILL.md`** from the provider skill
root and follow the `DevOps API Access` section for authentication and request
conventions. Do not skip this step.

### Path Resolution Failure

If the expected provider path does not exist, **stop immediately** and
report the error to the user. Do **not** attempt alternative searches
such as `find`, recursive `glob`, or expanding the search scope.

## Required Argument Workaround

When calling `devops_http.sh`, always pass at least one `--header` argument even
when no custom HTTP header is needed. Use a harmless request identifier such as:

```bash
--header "X-Request-ID: <purpose>"
```

Omitting `--header` causes the script to fail due to empty-array handling under
`set -u`.

## Token Pre-check

Before executing any API call, **you MUST confirm** that `DEVOPS_API_TOKEN` is available.
Check in this order:

1. **Context** — If the user has already provided the token in the current
   conversation, use it directly without asking again.
2. **Shell environment variable** — Run `echo $DEVOPS_API_TOKEN` to check
   whether it is already exported in the shell.

If neither source provides a token, pause execution and report to the user:

- Which OPS environment the request targets (`prod`, `staging`, or `dev`).
- That `DEVOPS_API_TOKEN` is required and ask the user to provide the value.

Example shell check:

```bash
echo $DEVOPS_API_TOKEN
```

If the output is empty and no token was given in context, stop and prompt the
user for the token before proceeding.

## Authoring Note

Subskill authoring checklist and reusable authoring template are maintained in
`dedicated-cloud-toolkit/README.md`.