# Generated Artifact API Catalog

Open Orchestra keeps the human-facing flow small: use `orchestra init` to create
or repair a workspace, and use `orchestra refresh` to reconcile managed
generated artifacts after initialization.

The lower-level commands in this catalog remain available as APIs for tests,
automation, integrations, and advanced troubleshooting. They should not be the
first commands shown to new users.

## API Tags

- `system`: manages generated files, instruction blocks, manifests, or runtime
  bootstrap artifacts.
- `process`: derives workflow, phase, skill, or playbook guidance from task
  state.
- `experience`: renders runtime-specific output for an agent, IDE, web console,
  or other user-facing integration.

## Safety Contract

Generated artifact APIs must preserve user-authored content outside managed
Open Orchestra blocks. `--check` and `--dry-run` must not write files. `--force`
may replace managed blocks, but it must not overwrite unrelated project
instructions.

Prefer these top-level commands for normal use:

```bash
orchestra init --check
orchestra init --force --target codex,claude
orchestra refresh --check --json
orchestra refresh --force --runtime-artifacts
```

## APIs

### `runtime bootstrap`

Tags: `system`, `experience`

Renders or upserts runtime bootstrap instructions for a specific agent target.
Use it when an integration needs a single target file instead of the full
workspace initialization flow.

```bash
orchestra runtime bootstrap --target codex --file AGENTS.md --check --json
orchestra runtime bootstrap --target claude --file CLAUDE.md --force
```

Representative JSON result:

```json
{
  "mode": "check",
  "target": "codex",
  "file": "AGENTS.md",
  "status": "unchanged",
  "managedBlock": "runtime-bootstrap",
  "changed": false,
  "blocked": false
}
```

### `instructions apply`

Tags: `system`

Applies an instruction manifest that may contain multiple managed blocks. Use it
for tests and bulk reconciliation, not for first-run onboarding.

```bash
orchestra instructions apply --manifest .agent-workflow/instructions.json --check --json
```

Representative manifest payload:

```json
{
  "version": 1,
  "entries": [
    {
      "file": "AGENTS.md",
      "blockId": "runtime-bootstrap",
      "target": "codex",
      "contentFile": ".agent-workflow/generated/codex-bootstrap.md"
    }
  ]
}
```

### `instructions block`

Tags: `system`

Upserts one managed instruction block into one file. Use it for focused
automation when the caller already knows the exact block and target file.

```bash
orchestra instructions block \
  --file AGENTS.md \
  --block runtime-bootstrap \
  --content-file .agent-workflow/generated/codex-bootstrap.md \
  --target codex \
  --dry-run \
  --json
```

Representative JSON result:

```json
{
  "file": "AGENTS.md",
  "blockId": "runtime-bootstrap",
  "target": "codex",
  "mode": "dry-run",
  "status": "changed",
  "changed": true
}
```

### `instructions imports`

Tags: `system`

Resolves imported instruction fragments from a registry entry. Use it when a
runtime or installer needs to preview composed instructions before writing a
managed block.

```bash
orchestra instructions imports \
  --registry .agent-workflow/instruction-registry.json \
  --entry codex-runtime-bootstrap \
  --target codex \
  --json
```

Representative JSON result:

```json
{
  "entry": "codex-runtime-bootstrap",
  "target": "codex",
  "imports": [
    {
      "id": "workflow-required",
      "source": "runtime-bootstrap"
    }
  ],
  "content": "Use Open Orchestra as the local control plane..."
}
```

### `instructions stale`

Tags: `system`

Detects stale managed instruction blocks by comparing embedded content hashes
with current generated content.

```bash
orchestra instructions stale --manifest .agent-workflow/instructions.json --json
```

Representative JSON result:

```json
{
  "stale": [
    {
      "file": "CLAUDE.md",
      "blockId": "runtime-bootstrap",
      "target": "claude",
      "expectedHash": "abc123",
      "actualHash": "def456"
    }
  ]
}
```

### `protocol render`

Tags: `process`, `experience`

Renders subagent collaboration protocol text without writing files.

```bash
orchestra protocol render --target codex --task STORY-001 --json
```

Representative JSON result:

```json
{
  "target": "codex",
  "task": "STORY-001",
  "sections": [
    "delegation boundaries",
    "handoff requirements",
    "lifecycle commands"
  ],
  "content": "Use runtime-native subagents only when the parent runtime supports them..."
}
```

### `protocol block`

Tags: `system`, `process`, `experience`

Upserts the rendered subagent protocol into a runtime instruction file.

```bash
orchestra protocol block --file AGENTS.md --target codex --task STORY-001 --check --json
```

Representative JSON result:

```json
{
  "file": "AGENTS.md",
  "blockId": "subagent-protocol",
  "target": "codex",
  "task": "STORY-001",
  "status": "unchanged"
}
```

### `skills plan`

Tags: `process`

Selects task-scoped skills from role, phase, paths, risks, and acceptance
criteria. This is a planning API; it does not write runtime files.

```bash
orchestra skills plan --task STORY-001 --json
```

Representative JSON result:

```json
{
  "task": "STORY-001",
  "selectedSkills": [
    {
      "id": "qa-evidence",
      "reason": "acceptance criteria require observable CLI evidence"
    }
  ]
}
```

### `skills advise`

Tags: `process`, `experience`

Selects skills from an advisory prompt without requiring a registered task.
Use it for advisory mode, discovery, and integrations that have not created a
workflow task yet.

```bash
orchestra skills advise \
  --prompt "Generate a release-ready Playwright plan for the web console" \
  --role qa \
  --phase qa \
  --json
```

Representative JSON result:

```json
{
  "role": "qa",
  "phase": "qa",
  "selectedSkills": [
    {
      "id": "qa-evidence",
      "activation": "Playwright evidence and acceptance coverage"
    }
  ]
}
```

### `skills render`

Tags: `process`, `experience`

Renders selected skills into target-specific text for Codex, Claude, Cursor,
VS Code, Windsurf, or generic runtimes.

```bash
orchestra skills render --target codex --task STORY-001 --json
orchestra skills render --target cursor --skills qa-evidence,diagram-export
```

Representative JSON result:

```json
{
  "target": "codex",
  "task": "STORY-001",
  "skills": [
    {
      "id": "qa-evidence",
      "title": "QA Evidence Pack"
    }
  ],
  "content": "When validating QA evidence, map every assertion to acceptance criteria..."
}
```

### `workflow render`

Tags: `process`, `experience`

Renders workflow phase guidance, optionally scoped to a runtime and phase.

```bash
orchestra workflow render --task STORY-001 --target claude --phase developer --json
```

Representative JSON result:

```json
{
  "task": "STORY-001",
  "target": "claude",
  "phase": "developer",
  "loadedPlaybooks": [
    "developer"
  ],
  "content": "Implement domain/model changes before command entry points..."
}
```

### `playbooks scaffold`

Tags: `system`, `process`

Creates missing phase playbook stubs. It should preserve existing playbooks and
is best used during project setup or repository maintenance.

```bash
orchestra playbooks scaffold --phase developer,qa --dry-run --json
```

Representative JSON result:

```json
{
  "mode": "dry-run",
  "created": [
    ".agent-workflow/playbooks/developer.md",
    ".agent-workflow/playbooks/qa.md"
  ],
  "unchanged": []
}
```

## Documentation Guidance

- Public onboarding should mention only `init` and `refresh` for generated
  artifact management.
- Reference docs may link to this catalog for advanced automation and testing.
- API examples should remain representative and avoid depending on local user
  paths, secrets, or generated IDs.