# Command Contracts

`orchestra commands manifest --json` is the supported discovery surface for
automation. Entries include command text, required and optional flags, JSON
support, surface classification, compatibility status, contract version, exit
codes, error shape, and reusable schema/message references.

## Compatibility

- `stable`: command supports `--json`; output must be parseable JSON and may add
  fields in minor releases.
- `experimental`: command is intended for humans or workflow mutation and should
  not be consumed as a stable machine contract unless a future schema is linked.

## Surfaces

- `public`: stable automation contract for project workflows, documentation,
  bootstrap files, and CI usage.
- `experimental`: supported CLI behavior, but not a frozen machine contract for
  `1.0.0`.
- `internal`: implementation or adapter support surface. It may expose `--json`
  for local tooling, but it is not part of the public 1.0 automation contract.

Public commands use contract version `1.0`, exit codes `0` and `1`, and the
generic JSON error contract unless a command-specific schema replaces it.

Config migration is exposed as a public contract through
`orchestra config migrate --json`. It is dry-run by default and requires
`--apply` before writing `.agent-workflow/config.json`.

## CLI Capability Manifest

`orchestra capabilities manifest --json` is the public discovery surface for
role-scoped command capabilities. It is intended for humans, the web UI, and
external runtimes that need official Orchestra commands before creating ad hoc
scripts.

The JSON payload includes:

- `manifestVersion`: stable capability manifest contract version.
- `scope`: selected `role`, `phase`, and `taskId` when provided.
- `commandConstruction`: executable and argv guidance. Consumers must pass the
  executable and args as separate argv entries and must not interpolate shell
  strings.
- `capabilities`: the full catalog when no role is selected.
- `exposed` and `omitted`: role/phase/task-scoped capabilities when a role or
  task is selected.

Use `--task <id>` to default scope from the task owner and task signals, or use
`--role <role> --phase <phase>` for runtime assignment prompts.

## Reusable Contracts

- `schemas/commands/generic-json-output.schema.json` defines the baseline JSON
  parseability contract for stable commands.
- `messages/commands/generic-json-output.md` documents the consumer guidance for
  stable JSON commands.

Command-specific schemas can replace the generic reference when a command output
is ready to be locked more tightly.

## Generated Artifact APIs

Open Orchestra keeps generated artifact operations user-facing through
`orchestra init` and `orchestra refresh`. Lower-level commands such as
`runtime bootstrap`, `instructions block`, `protocol block`, `skills render`,
`workflow render`, and `playbooks scaffold` remain available as advanced APIs
for tests, integrations, and troubleshooting.

See [generated-artifact-api-catalog.md](generated-artifact-api-catalog.md) for
API tags, examples, representative JSON payloads, and safety semantics.