# Open Orchestra 1.0.0 Adoption Guide This guide is the documentation map for teams evaluating or adopting Open Orchestra. Start here, then follow the focused document for the workflow you are running. ## Documentation Map | Need | Start Here | | --- | --- | | Install and run the first task | [Quickstart](#quickstart) | | Understand the control plane | [architecture.md](architecture.md) | | Choose the stable command surface | [core-command-surface.md](core-command-surface.md) | | Automate against JSON contracts | [command-contracts.md](command-contracts.md) | | Run governed task delivery | [autonomous-workflow.md](autonomous-workflow.md) | | Use Claude, Codex, OpenCode, Cursor, VS Code, or Windsurf | [runtime-adapters.md](runtime-adapters.md) and [runtime-llm-flow.md](runtime-llm-flow.md) | | Configure provider routing | [runtime-llm-flow.md](runtime-llm-flow.md) | | Sync tracker-backed work | [tracker-adapter-contract.md](tracker-adapter-contract.md) | | Use the local web console | [orchestra-mvp.md](orchestra-mvp.md) | | Understand public site content generation | [site-content-workflow.md](site-content-workflow.md) | | Prepare release evidence | [release-test-matrix.md](release-test-matrix.md) | | Manage memory, prompts, and lessons | [source-of-truth-and-agent-learning.md](source-of-truth-and-agent-learning.md) | | Extend skills or adapters | [extension-contracts.md](extension-contracts.md) | | Upgrade pre-1.0 workspaces | [Migration](#migration) | ## Quickstart The first run should stay local and deterministic. No provider token is required. First visible value means a completed local workflow run and release-candidate preview in under ten minutes. ```bash npm install -g @jterrats/open-orchestra@latest 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, add explicit effort baselines, architecture sizing, human gates, command evidence, and QA review before release checks: ```bash orchestra estimate --task STORY-001 --sizing s --solo-days 1 --ai-unguided-days 0.5 --ai-guided-days 0.25 orchestra decision add --task STORY-001 --owner architect --title "Story sizing" --decision "s 2 points" --context "Production story" --consequences "Developer phase can start" orchestra workflow run --task STORY-001 --gates phase orchestra evidence add --task STORY-001 --role developer --type command --summary "Validation passed" --command "npm run precommit" --exit-code 0 orchestra review --task STORY-001 --role qa --result approve --findings "Acceptance criteria covered" --recommendation "Ready for release review" orchestra release check --json ``` Do not approve workflow gates just because the CLI reached a pause. The `po->architect` gate requires user-validated scope, assumptions, non-goals, priority, acceptance criteria, and sizing context. The `qa->release` gate requires real implementation evidence, exact validation commands, QA findings, and BA/PO plus Architect review when business behavior or technical contracts changed. If a generated handoff says `Acceptance Criteria: none`, use the linked issue or task as the source of truth, record the gap, and block release until the missing criteria/evidence are fixed or explicitly risk-accepted. ## Concepts Open Orchestra is a local control plane. The parent runtime remains the active agent. Orchestra coordinates workflow state through task files, events, handoffs, reviews, evidence, gates, locks, runtime briefs, and release reports. Provider configuration is optional. Teams can start with deterministic local workflow phases, then route roles to OpenAI, Anthropic, Gemini, Ollama, or other runtime adapters when credentials and policy are ready. ## Workflow Examples Solo developer: ```bash orchestra task add --id SOLO-001 --title "Fix a small CLI bug" --owner developer --paths "src/cli.ts,test/orchestra.test.js" orchestra workflow run --task SOLO-001 --gates none orchestra release check --json ``` Team workflow with human gates: ```bash orchestra workflow run --task TEAM-001 --gates phase orchestra workflow gate-approve --run --gate "po->architect" --approver "" --rationale "User validated the story, definitions, assumptions, non-goals, priority, and acceptance criteria" orchestra workflow run --task TEAM-001 --resume ``` Quote gate ids in shells so `po->architect` and `qa->release` are passed as literal values rather than interpreted as output redirection. Local-only provider: ```bash orchestra model profile set --name local --role developer --provider ollama --model llama3.1 orchestra model profile apply --name local orchestra model profile smoke --name local --json ``` Tracker-integrated workflow: ```bash orchestra github sync --issue 123 --json orchestra tracker sync --tracker jira --remote PROJ-123 --issue-file jira-123.json --json orchestra task list --json --status pending,blocked,in_progress ``` ## Provider And Tracker Safety Never store raw provider keys in workflow files, docs, prompt registries, or lessons. Use environment variables or provider-specific secret storage, and keep `orchestra model providers --json` output sanitized before attaching evidence. If `gh` or another tracker CLI is unavailable, use the MCP-backed tracker fallback described in [tracker-adapter-contract.md](tracker-adapter-contract.md). Fallbacks should produce normalized task metadata or a clear pending finding; they should not invent remote state. ## Release Operations Before a production release candidate, run: ```bash npm run precommit npm run test:e2e npm run release:matrix -- --json orchestra release check --json ``` Attach command evidence with `orchestra evidence add`, then record QA and release reviews with `orchestra review`. Documentation and public-site changes also need Technical Writer review before release readiness. Use [site-content-workflow.md](site-content-workflow.md) for the generated site content contract, Technical Writer triggers, and site QA evidence expectations. ## Troubleshooting - Run `orchestra health --json` when CLI, Node, Git, GitHub, Playwright, or workspace readiness is unclear. - Run `orchestra validate --pre-run --task --json` before implementation when workflow gates or evidence appear incomplete. - Run `orchestra memory governance --json` if prompt registry or lesson history is too large or may contain sensitive values. - Run `orchestra diagnostics bundle --output support/orchestra-diagnostics.json` before handing off environment-specific failures. ## Migration For pre-1.0 workspaces: 1. Upgrade the package with `npm install -g @jterrats/open-orchestra@latest`. 2. Run `orchestra upgrade --smoke --json`. 3. Run `orchestra config migrate --dry-run --json`, then apply the migration only after reviewing the planned backup and normalized config. 4. Run `orchestra refresh --check --json` to detect stale generated bootstrap or runtime files. 5. Run `orchestra validate --pre-run --task --json` before resuming active tasks. `orchestra init` and `orchestra refresh` preserve existing project instructions. When files such as `AGENTS.md` or `ORCHESTRA.md` already exist, Open Orchestra adds or updates only its marked managed block: ```md ... ``` Rules outside that block remain project-owned. If a managed block was manually edited, refresh reports drift and requires `--force` before replacing the block. The forced refresh still replaces only the Open Orchestra block; it does not rewrite the full instruction file. Migration must preserve `.agent-workflow/` history. Archive stale tasks or lessons with explicit commands instead of manually editing runtime files.