# Tracker Adapter Contract

Open Orchestra currently ships a GitHub-oriented tracker command:

```bash
orchestra github sync --issue <number> --task <id> --comment --json
orchestra tracker sync --tracker jira --remote PROJ-123 --issue-file jira-123.json --json
```

The product contract is broader than GitHub CLI. A runtime may use `gh` when it
is installed and authenticated, or fall back to an MCP-backed tracker skill when
the user works in GitHub, Jira, Bitbucket, GitLab, Azure DevOps, Linear, or a
custom issue system.

## Resolution Order

1. Use the native CLI transport when the workspace explicitly targets it and the
   CLI is installed, authenticated, and authorized for the repository.
2. Use `--transport mcp-skill` when the native CLI is unavailable or the runtime
   exposes tracker tools through MCP.
3. If neither transport is available, keep the local task and record a review
   finding that tracker sync is pending instead of inventing remote state.

## Common Adapter Shape

Every tracker adapter should provide the same normalized fields to Open
Orchestra. Runtime MCP skills, Jira/GitLab/Bitbucket CLIs, or custom bridge
scripts should write this shape to a workspace-local JSON file and pass it to
`orchestra tracker sync --issue-file <file>`:

| Field | Meaning |
| --- | --- |
| `tracker` | Provider name such as `github`, `jira`, `gitlab`, `bitbucket`, or `custom`. |
| `remoteId` | Provider issue key or number. |
| `url` | Canonical issue URL. |
| `title` | Issue title. |
| `body` | Issue body or description. |
| `state` | Provider state normalized to `open`, `in_progress`, `blocked`, or `done` when possible. |
| `labels` | Provider tags, labels, components, or issue types. |
| `assignees` | User handles or display names. |
| `acceptanceCriteria` | Explicit acceptance criteria extracted from the issue. |
| `updatedAt` | Provider last-updated timestamp. |

Writes should support comment, status update, close, and accepted-risk note when
the provider allows them. Missing write support should be reported as a transport
capability gap, not treated as successful sync.

The generic sync command maps the normalized issue into local task fields,
detects existing-link conflicts before writing, and records local evidence when
the sync is applied. Live remote reads and writes remain adapter-owned; the CLI
does not fabricate Jira, GitLab, Bitbucket, or MCP calls when no adapter runner
is available.

## MCP Fallback Requirements

MCP tracker tools must:

- Use HTTPS endpoints and the repository's approved auth flow.
- Avoid storing raw tokens in workflow artifacts, logs, or prompt registries.
- Return structured data that can be mapped to the common adapter shape.
- Make write operations explicit: comment, status transition, close, reopen, and
  accepted-risk note are separate capabilities.
- Record which transport handled the sync in evidence or event metadata.

## GitHub Compatibility

The GitHub command remains the first-class implementation:

```bash
orchestra github sync --issue 180 --task OO-176 --owner technical_writer --comment --json
orchestra github sync --issue 180 --task OO-176 --transport mcp-skill --dry-run --json
```

Use the MCP form for environments where `gh` is not installed but the active
runtime has a GitHub MCP server with issue read/write tools.