@jterrats/open-orchestra 0.5.0 → 0.5.2

package/docs/end-to-end-demo.md

@@ -0,0 +1,87 @@
+# Reproducible End-to-End Demo
+
+This demo uses only local workflow state and the built-in fake provider path. It
+does not require OpenAI, Anthropic, GitHub, or tracker credentials.
+
+Run it in a disposable directory:
+
+```bash
+mkdir open-orchestra-demo
+cd open-orchestra-demo
+npm install -g @jterrats/open-orchestra
+orchestra init --confirm-unknown
+orchestra health --json
+```
+
+In a disposable empty directory, `health` may report a workspace-classification
+warning while still reporting workflow readiness as passed. Real project
+directories should have project signals such as a package manager or source tree.
+
+## 1. Create a Governed Task
+
+```bash
+orchestra task add \
+  --id DEMO-001 \
+  --title "Ship a governed README update" \
+  --owner product_owner \
+  --paths "README.md"
+
+orchestra estimate \
+  --task DEMO-001 \
+  --sizing s \
+  --solo-days 1 \
+  --ai-unguided-days 0.5 \
+  --confidence medium
+```
+
+## 2. Satisfy the Architect Sizing Gate
+
+The autonomous workflow always requires architect sizing before developer work.
+
+```bash
+orchestra decision add \
+  --task DEMO-001 \
+  --owner architect \
+  --title "Story sizing" \
+  --decision "s 2 points" \
+  --context "Local fake-provider demo" \
+  --consequences "Developer phase can start"
+```
+
+## 3. Run the Workflow
+
+```bash
+orchestra workflow run --task DEMO-001 --gates none
+orchestra workflow runs --json
+```
+
+Expected result: the run creates PM, PO, architect, developer, QA, and release
+phase records in `.agent-workflow/` and completes without provider API keys.
+
+## 4. Attach Evidence and Review
+
+```bash
+orchestra evidence add \
+  --task DEMO-001 \
+  --role developer \
+  --type command \
+  --summary "Demo workflow completed with fake provider"
+
+orchestra review \
+  --task DEMO-001 \
+  --role qa \
+  --result approve \
+  --findings "Demo artifacts are present and workflow completed" \
+  --recommendation "Use this path for local onboarding"
+```
+
+## 5. Inspect Release Readiness
+
+```bash
+orchestra release candidate --version 0.0.0-demo --dry-run --json
+orchestra benchmark --task DEMO-001
+orchestra summary --json
+```
+
+The demo is complete when the workflow run is done, evidence and QA review exist,
+and the release candidate dry run reports the remaining gaps explicitly.

package/docs/runtime-llm-flow.md

@@ -92,15 +92,17 @@ workflow execution only when the workflow config has approved routing.
 Model routing controls which provider/model each role uses during autonomous
 workflow phases. The default `none` provider keeps the deterministic workflow
 behavior. Configure a role or default route to `fake` for local structured
-execution tests, or to `openai` to use the OpenAI Responses API through the
-native provider adapter. Use `anthropic` to route phases to Claude models
-through the Anthropic Messages API.
+execution tests, `openai` for the OpenAI Responses API, `anthropic` for the
+Anthropic Messages API, `gemini` for the Gemini `generateContent` API, or
+`ollama` for a local OpenAI-compatible Ollama endpoint.
 
 ```bash
 orchestra model providers --json
 orchestra model set-role --role qa --provider fake --model fake-model
 OPENAI_API_KEY=... orchestra model set-role --role architect --provider openai --model gpt-5.2
 ANTHROPIC_API_KEY=... orchestra model set-role --role qa --provider anthropic --model claude-sonnet-4-20250514
+GEMINI_API_KEY=... orchestra model set-role --role product_manager --provider gemini --model gemini-2.5-pro
+orchestra model set-role --role developer --provider ollama --model llama3.2
 orchestra model provenance list --json
 orchestra budget check --json
 orchestra workflow run --task STORY-001 --gates phase
@@ -117,12 +119,23 @@ optionally `ANTHROPIC_BASE_URL` for an HTTPS-compatible endpoint. It uses
 Claude Messages API responses are normalized through text content rather than
 OpenAI-style JSON schema response formatting.
 
+The Gemini adapter reads `GEMINI_API_KEY` or `GOOGLE_API_KEY` from the
+environment. For local secret files, set `GEMINI_API_KEY_FILE` or
+`GOOGLE_API_KEY_FILE` to an absolute path containing only the key value. The
+adapter also reads optional `GEMINI_BASE_URL`; the base URL must be HTTPS and
+defaults to `https://generativelanguage.googleapis.com`.
+
+The Ollama adapter defaults to `http://localhost:11434/v1` and uses the
+OpenAI-compatible `/chat/completions` endpoint. Set `OLLAMA_BASE_URL` for a
+custom local or remote endpoint and `OLLAMA_API_KEY` when the endpoint requires
+one.
+
 ## Runtime Execution
 
 Runtime execution is separate from model provider routing. `ModelProvider`
 adapters call vendor APIs directly and therefore require provider API keys.
 Runtime execution adapters prepare work for an already-authenticated runtime
-such as Claude CLI, Codex CLI, Cursor, VS Code, or Windsurf.
+such as Claude CLI, Codex CLI, OpenCode CLI, Cursor, VS Code, or Windsurf.
 
 Use runtime execution when the user wants the active CLI/IDE agent to perform
 the work and does not want Orchestra to call OpenAI, Anthropic, or another
@@ -131,6 +144,7 @@ vendor API directly:
 ```bash
 orchestra runtime adapters --json
 orchestra runtime brief --task STORY-001 --runtime claude-cli
+orchestra runtime brief --task STORY-001 --runtime opencode-cli
 orchestra runtime delegate-plan --task STORY-001 --runtime claude-cli --roles architect,developer,qa
 orchestra runtime handoff --task STORY-001 --runtime claude-cli --artifact .agent-workflow/runs/STORY-001-runtime-claude-cli-delegation.md
 ```

package/docs/skill-loading-strategy.md

@@ -61,6 +61,7 @@ Skill manifests should be able to declare `sourceGroups` so the orchestrator can
 - `pr-review`: produce review findings, PR summary, risks, rollout notes, and missing-test gaps.
 - `playwright-evidence`: plan browser automation and attach screenshots, traces, videos, and reports.
 - `backlog-sync`: keep GitHub issues, local stories, and workflow tasks aligned.
+- `doc-sync`: keep architecture docs, changelog, onboarding, runbooks, site copy, and prompt registers aligned with delivered changes.
 - `release-readiness`: validate gates, rollback, observability, support, and customer-impact evidence.
 - `model-evaluation`: run prompt/model/provider-routing evaluations and compare outputs.
 - `source-of-truth`: select authoritative project, vendor, and workflow sources before acting.

package/docs/tracker-adapter-contract.md

@@ -0,0 +1,66 @@
+# Tracker Adapter Contract
+
+Open Orchestra currently ships a GitHub-oriented tracker command:
+
+```bash
+orchestra github sync --issue <number> --task <id> --comment --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:
+
+| 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.
+
+## 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.

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@jterrats/open-orchestra",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "type": "module",
+  "workspaces": [
+    "site"
+  ],
   "bin": {
     "orchestra": "bin/orchestra.js"
   },
@@ -9,16 +12,18 @@
     "build": "tsc && npm run build:web",
     "typecheck": "tsc --noEmit",
     "test": "npm run build && node --test test/**/*.js extensions/**/*.test.cjs",
-    "test:e2e": "npm run build && playwright test",
+    "test:e2e": "npm run build && npm run site:build && playwright test",
     "test:e2e:init": "node --test e2e/init-onboarding.test.js",
-    "lint": "eslint . && prettier --check \"{bin,e2e,scripts,test,src}/**/*.js\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.{js,json}\"",
-    "format": "prettier --write \"{bin,e2e,scripts,test,src}/**/*.js\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.{js,json}\"",
+    "lint": "eslint . && prettier --check \"{bin,e2e,scripts,test,src}/**/*.js\" \"site/src/**/*.{css,js,jsx}\" \"site/*.{html,js,json}\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.{js,json}\"",
+    "format": "prettier --write \"{bin,e2e,scripts,test,src}/**/*.js\" \"site/src/**/*.{css,js,jsx}\" \"site/*.{html,js,json}\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.{js,json}\"",
     "secret-scan": "node scripts/secret-scan.js",
     "validate:workflow": "node scripts/validate-workflow.js",
     "precommit": "npm run lint && npm run typecheck && npm run secret-scan && npm test && npm run validate:workflow",
     "prepack": "npm run build",
     "hooks:install": "git config core.hooksPath .githooks",
-    "build:web": "esbuild src/web-console-client.js --bundle --format=esm --platform=browser --target=es2022 --outfile=dist/assets/web-console.js"
+    "build:web": "esbuild src/web-console-client.js --bundle --format=esm --platform=browser --target=es2022 --outfile=dist/assets/web-console.js",
+    "site:build": "npm --workspace @jterrats/open-orchestra-site run build",
+    "site:dev": "npm --workspace @jterrats/open-orchestra-site run dev -- --host 127.0.0.1"
   },
   "engines": {
     "node": ">=22"

package/skills/doc-sync/SKILL.md

@@ -0,0 +1,40 @@
+# Doc Sync
+
+Keep architecture docs, changelog, onboarding, runbooks, site copy, and prompt registers aligned with delivered changes.
+
+## When To Load
+
+- Trigger: `documentation`
+- Trigger: `docs`
+- Trigger: `changelog`
+- Trigger: `readme`
+- Trigger: `quickstart`
+- Trigger: `runbook`
+- Trigger: `architecture`
+- Trigger: `adr`
+- Trigger: `release notes`
+- Trigger: `public site`
+- Trigger: `prompt registry`
+
+## Procedure
+
+- Identify changed behavior, architecture, release surface, workflows, commands, and user-facing copy from the task, issue, diff, and evidence.
+- Update the smallest authoritative documentation surfaces for the audience: README for onboarding, CHANGELOG for release history, `docs/` for architecture and runbooks, `.generated-prompts/` for prompt intent, and the public site for product-facing guidance.
+- Keep code, service, and domain generation prompts traceable: update `.generated-prompts/code.md` or `.generated-prompts/services.md` after substantial class, model, service, controller, or module changes.
+- Keep documentation and diagram prompts traceable: update `.generated-prompts/docs.md` or `.generated-prompts/diagrams.md` after substantial docs, architecture, ADR, runbook, changelog, or Mermaid changes.
+- Validate command examples against `orchestra commands manifest --json`, `orchestra --help`, or the repo-local `node bin/orchestra.js` during Open Orchestra development.
+- If README, docs, or site onboarding changes, check the sibling surfaces so quickstart language, command names, and release positioning do not drift.
+- Record unresolved documentation gaps as review findings or follow-up tasks instead of burying them in prose.
+
+## Surface Checklist
+
+- Architecture changes: `docs/architecture.md`, ADRs, Mermaid diagrams, public site architecture section, `.generated-prompts/diagrams.md`.
+- Release changes: `CHANGELOG.md`, release notes, rollback and observability notes, `.generated-prompts/docs.md`.
+- CLI or workflow changes: `README.md`, command reference docs, public site quickstart, `.generated-prompts/code.md`.
+- Product or support changes: public site, user guides, known issues, support FAQs, `.generated-prompts/docs.md`.
+
+## Evidence
+
+- `file`
+- `report`
+- `command`

package/skills/doc-sync/manifest.json

@@ -0,0 +1,58 @@
+{
+  "id": "doc-sync",
+  "name": "Doc Sync",
+  "summary": "Keep architecture docs, changelog, onboarding, runbooks, site copy, and prompt registers aligned with delivered changes.",
+  "triggers": [
+    "doc-sync",
+    "documentation",
+    "docs",
+    "changelog",
+    "readme",
+    "quickstart",
+    "runbook",
+    "architecture",
+    "adr",
+    "release notes",
+    "public site",
+    "prompt registry"
+  ],
+  "roles": [
+    "technical_writer",
+    "release_manager",
+    "architect",
+    "product_manager",
+    "product_owner",
+    "platform_engineer",
+    "support_customer_ops",
+    "parent"
+  ],
+  "capabilities": [
+    "documentation-sync",
+    "release-notes",
+    "architecture-communication",
+    "onboarding",
+    "support-readiness"
+  ],
+  "riskAreas": [
+    "documentation",
+    "architecture",
+    "release",
+    "governance"
+  ],
+  "sourceGroups": [
+    "project-instructions",
+    "product-backlog",
+    "architecture",
+    "codebase",
+    "devops-runtime",
+    "quality-security",
+    "agent-memory"
+  ],
+  "evidence": [
+    "file",
+    "report",
+    "command"
+  ],
+  "loadBudget": "normal",
+  "entry": "skills/doc-sync/SKILL.md"
+}