# Extension Contracts

Open Orchestra discovers local extensions from:

```text
.agent-workflow/extensions/<extension-id>/manifest.json
```

The manifest is metadata only. Discovery and validation do not import or execute
extension code.

## Manifest

```json
{
  "id": "acme-tracker",
  "name": "Acme Tracker Adapter",
  "version": "1.0.0",
  "compatibility": { "orchestra": "^1.0.0" },
  "extensionPoints": ["tracker-adapter"],
  "entry": "adapter.js",
  "capabilities": ["normalized-issue-sync"],
  "riskAreas": ["network", "tracker-state"]
}
```

Supported extension points for the 1.0 contract are:

- `skill`
- `tracker-adapter`
- `provider-adapter`
- `phase-playbook`
- `refresh-target`

`entry` must be a relative path inside the extension directory. Absolute paths
and traversal are rejected. Provider adapter extensions are currently
metadata-only until runtime provider loading is stabilized.

## Commands

```bash
orchestra extensions list --json
orchestra extensions validate --json
```

## Provider-Like Example

```json
{
  "id": "acme-models",
  "name": "Acme Models Provider",
  "version": "1.0.0",
  "compatibility": { "orchestra": "^1.0.0" },
  "extensionPoints": ["provider-adapter"],
  "entry": "provider.js",
  "capabilities": ["chat-completions", "json-mode"],
  "riskAreas": ["secrets", "network"]
}
```

## Tracker-Like Example

```json
{
  "id": "acme-tracker",
  "name": "Acme Tracker Adapter",
  "version": "1.0.0",
  "compatibility": { "orchestra": "^1.0.0" },
  "extensionPoints": ["tracker-adapter"],
  "entry": "tracker.js",
  "capabilities": ["normalized-issue-sync"],
  "riskAreas": ["network", "tracker-state"]
}
```

## Stability

Stable for 1.0.0: manifest shape, discovery path, extension point names, local
path safety validation, and JSON output from `extensions list` and
`extensions validate`.

Experimental: dynamic code loading, provider runtime registration, tracker live
transport execution, and generated-file refresh target execution.