# Core Command Surface

Open Orchestra exposes many commands because it covers intake, workflow, evidence,
runtime adapters, release readiness, and local memory. Product onboarding should
not present every command at once. Use this surface to decide what belongs in
README, the public site, generated runtime bootstrap text, and full reference
docs.

The authoritative machine-readable reference remains:

```bash
orchestra commands manifest --json
```

## Core Commands

Core commands are the first screen for a new project or a production delivery
workflow. They are stable enough to appear in onboarding and public examples.

For first visible value, show this compact sequence before introducing every
artifact type:

```bash
orchestra init
orchestra health --json
orchestra task add --id DEMO-001 --title "Ship a governed README update" --owner developer --paths "README.md"
orchestra workflow run --task DEMO-001 --gates none
orchestra status
orchestra release candidate --dry-run --json
```

For production delivery, follow with estimates, architecture sizing decisions,
human gates, evidence, QA reviews, and `orchestra release check --json`.

| Job                                       | Commands                                                                                                                        |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Install and verify                        | `orchestra version`, `orchestra upgrade --smoke --json`                                                                         |
| Initialize workspace                      | `orchestra init`, `orchestra health --json`, `orchestra status`                                                                 |
| Create and inspect work                   | `orchestra task add`, `orchestra task list`, `orchestra task show`                                                              |
| Run governed delivery                     | `orchestra workflow run`, `orchestra workflow runs`                                                                             |
| Inspect workflow shape and playbooks      | `orchestra workflow phase-plan --task <id>`, `orchestra workflow render --task <id> --phase <phase>`                            |
| Resolve workflow gates and clarifications | `orchestra decision add`, `orchestra workflow gate-approve`, `orchestra workflow clarify`, `orchestra workflow clarify-respond` |
| Record delivery proof                     | `orchestra evidence add`, `orchestra review`                                                                                    |
| Plan QA automation                        | `orchestra qa coverage --task <id>`, `orchestra playwright plan --task <id>`                                                    |
| Sync tracker state                        | `orchestra github sync --issue <number>`, `orchestra tracker sync --tracker <provider> --remote <id> --issue-file <file>`       |
| Check release readiness                   | `orchestra release check --json`, `orchestra release candidate --dry-run --json`                                                |

## Run Command Guidance

`orchestra workflow run` is the governed delivery lifecycle. It creates phase
sub-tasks, handoffs, run state, and gates across PM, PO, Architect, Developer,
QA, and Release. Use it for product work, issue delivery, QA handoff, release
readiness, and dogfooding the end-to-end process.

`orchestra run` executes the task's local execution plan. It is useful for
lower-level plan execution and budget/fallback validation, but it does not
replace the autonomous lifecycle or its phase gates.

For the full workflow narrative, phase matrix, gate-versus-clarify decision
table, and playbook authoring guidance, see
[autonomous-workflow.md](autonomous-workflow.md).

## Advanced Commands

Advanced commands are useful after the team understands the core lifecycle. They
should be linked from onboarding, not mixed into first-run copy.

- Planning and coordination: `orchestra graph plan`, `orchestra graph run-next`,
  `orchestra graph run-ready`, `orchestra delegation decide`,
  `orchestra collaboration recommend`.
- Runtime and skills: `orchestra runtime brief`,
  `orchestra runtime delegate-plan`, `orchestra skills plan`,
  `orchestra skills render`, `orchestra protocol render`.
- Extensions: `orchestra extensions list --json`,
  `orchestra extensions validate --json`.
- Provider profiles: `orchestra model profile set`,
  `orchestra model profile apply`, `orchestra model profile smoke`,
  `orchestra model providers`.
- Generated-file operations: `orchestra refresh --check --json`,
  `orchestra refresh --dry-run`, `orchestra refresh --force`,
  `orchestra cursor canvas status --json`,
  `orchestra cursor canvas sync --dry-run --json`.
- Memory and source selection: `orchestra memory query`,
  `orchestra memory hook`, `orchestra memory governance`,
  `orchestra sources list`, `orchestra lessons list`,
  `orchestra lessons archive`, `orchestra lessons redact`,
  `orchestra lessons prune`.
- Metrics and cost: `orchestra estimate`, `orchestra benchmark`,
  `orchestra burndown`, `orchestra usage`, `orchestra budget check`.
- Governance policy: `orchestra policy evaluate` checks routine, elevated,
  major, and destructive action tiers from `.agent-workflow/policy.json` and
  creates approval artifacts for major or destructive actions.
- Local control surfaces: `orchestra web`, `orchestra serve`,
  `orchestra roles list`, `orchestra config show`.

## Experimental Commands

Experimental commands mutate local workflow state, depend on environment-specific
tooling, or expose lower-level integration surfaces. Keep them in reference docs
unless a specific workflow needs them.

- Instruction management: `orchestra instructions apply`,
  `orchestra instructions block`, `orchestra instructions imports`,
  `orchestra instructions stale`.
- Generated artifact APIs: `orchestra runtime bootstrap`,
  `orchestra protocol block`, `orchestra skills render`,
  `orchestra workflow render`, and `orchestra playbooks scaffold`. Keep normal
  user guidance centered on `orchestra init` and `orchestra refresh`; use
  [generated-artifact-api-catalog.md](generated-artifact-api-catalog.md) for API
  examples.
- MCP OAuth proxy: `orchestra mcp oauth-proxy evaluate`,
  `orchestra mcp oauth-proxy start`, `orchestra mcp oauth-proxy token`.
- Release mechanics: `orchestra release tag`, `orchestra release evidence`.
- Low-level approvals and locks: `orchestra approvals approve`,
  `orchestra approvals reject`, `orchestra lock claim`, `orchestra lock release`.
- Test and model internals: `orchestra playwright evidence`,
  `orchestra model set-role`, `orchestra model complete-fake`,
  `orchestra model provenance add`.

## Documentation Rule

Do not duplicate the full command manifest in README or the site. Show the core
path, then link to `orchestra -h` for human onboarding,
`orchestra help commands` for the full CLI catalog, and
`orchestra commands manifest --json` plus [command-contracts.md](command-contracts.md)
for automation consumers.