@jterrats/open-orchestra 0.4.2-beta.1 → 0.5.0-beta.0

package/docs/runtime-adapters.md

@@ -7,7 +7,7 @@ payload support, and usage guidance in one place.
 ## Adapter Catalog
 
 ```bash
-node bin/orchestra.js runtime adapters --json
+orchestra runtime adapters --json
 ```
 
 Current targets:
@@ -25,28 +25,32 @@ Current targets:
 Default project init keeps the current compact bootstrap behavior:
 
 ```bash
-node bin/orchestra.js init
+orchestra init
 ```
 
 Generate only selected runtime files:
 
 ```bash
-node bin/orchestra.js init --target claude,cursor,windsurf
+orchestra init --target claude,cursor,windsurf
 ```
 
 Advisory mode creates workflow state without root instruction files unless a
 target is explicit:
 
 ```bash
-node bin/orchestra.js init --advisory
-node bin/orchestra.js init --advisory --target claude
+orchestra init --advisory
+orchestra init --advisory --target claude
 ```
 
+It also writes portable planning artifacts under
+`.agent-workflow/advisory/`: a README, role guides, decision template, and a
+project task export that can be moved into a confirmed project workspace.
+
 Unsafe roots are blocked before writes. Unknown non-temp directories require an
 explicit confirmation:
 
 ```bash
-node bin/orchestra.js init --confirm-unknown
+orchestra init --confirm-unknown
 ```
 
 ## Runtime Loop
@@ -54,13 +58,14 @@ node bin/orchestra.js init --confirm-unknown
 After init, any runtime should use the same local control-plane loop:
 
 ```bash
-node bin/orchestra.js health --json
-node bin/orchestra.js task list --json
-node bin/orchestra.js context --task STORY-001 --json
-node bin/orchestra.js delegation decide --task STORY-001 --json
-node bin/orchestra.js skills render --target codex --task STORY-001
-node bin/orchestra.js protocol render --target codex --task STORY-001
-node bin/orchestra.js workflow render --target codex --task STORY-001
+orchestra health --json
+orchestra task list --json
+orchestra context --task STORY-001 --json
+orchestra delegation decide --task STORY-001 --json
+orchestra memory hook --point before_plan --task STORY-001 --json
+orchestra skills render --target codex --task STORY-001
+orchestra protocol render --target codex --task STORY-001
+orchestra workflow render --target codex --task STORY-001
 ```
 
 Change `--target` to the runtime that is executing the work. The workflow state,
@@ -72,7 +77,7 @@ The local web console exposes workspace classification and supported runtime
 targets through:
 
 ```bash
-node bin/orchestra.js web
+orchestra web
 ```
 
 The API contracts are:

package/docs/runtime-llm-flow.md

@@ -15,21 +15,22 @@ that phase and records phase artifacts plus model provenance.
 Use this sequence for a new project or a new task:
 
 ```bash
-node bin/orchestra.js init
-node bin/orchestra.js health --json
-node bin/orchestra.js task add --id STORY-001 --title "Short title" --owner developer --goal "Outcome"
-node bin/orchestra.js context --task STORY-001 --json
-node bin/orchestra.js delegation decide --task STORY-001 --json
-node bin/orchestra.js plan --task STORY-001 --json
-node bin/orchestra.js skills plan --task STORY-001 --json
-node bin/orchestra.js skills render --target codex --task STORY-001
-node bin/orchestra.js protocol render --target codex --task STORY-001
-node bin/orchestra.js workflow render --target codex --task STORY-001
-node bin/orchestra.js commands manifest --json
-node bin/orchestra.js runtime bootstrap --target codex
-node bin/orchestra.js evidence add --task STORY-001 --role developer --type command --summary "npm run precommit passed" --command "npm run precommit" --exit-code 0
-node bin/orchestra.js gate --gate architecture --task STORY-001
-node bin/orchestra.js summary --json
+orchestra init
+orchestra health --json
+orchestra task add --id STORY-001 --title "Short title" --owner developer --goal "Outcome"
+orchestra context --task STORY-001 --json
+orchestra delegation decide --task STORY-001 --json
+orchestra plan --task STORY-001 --json
+orchestra memory hook --point before_plan --task STORY-001 --json
+orchestra skills plan --task STORY-001 --json
+orchestra skills render --target codex --task STORY-001
+orchestra protocol render --target codex --task STORY-001
+orchestra workflow render --target codex --task STORY-001
+orchestra commands manifest --json
+orchestra runtime bootstrap --target codex
+orchestra evidence add --task STORY-001 --role developer --type command --summary "npm run precommit passed" --command "npm run precommit" --exit-code 0
+orchestra gate --gate architecture --task STORY-001
+orchestra summary --json
 ```
 
 Use `--target claude`, `--target cursor`, `--target codex`, `--target vscode`,
@@ -44,8 +45,8 @@ always-loaded context.
 Use explicit init targets when a project should generate runtime-specific files:
 
 ```bash
-node bin/orchestra.js runtime adapters --json
-node bin/orchestra.js init --target claude,cursor,windsurf
+orchestra runtime adapters --json
+orchestra init --target claude,cursor,windsurf
 ```
 
 ## Parent Agent Prompts
@@ -96,13 +97,13 @@ native provider adapter. Use `anthropic` to route phases to Claude models
 through the Anthropic Messages API.
 
 ```bash
-node bin/orchestra.js model providers --json
-node bin/orchestra.js model set-role --role qa --provider fake --model fake-model
-OPENAI_API_KEY=... node bin/orchestra.js model set-role --role architect --provider openai --model gpt-5.2
-ANTHROPIC_API_KEY=... node bin/orchestra.js model set-role --role qa --provider anthropic --model claude-sonnet-4-20250514
-node bin/orchestra.js model provenance list --json
-node bin/orchestra.js budget check --json
-node bin/orchestra.js workflow run --task STORY-001 --gates phase
+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
+orchestra model provenance list --json
+orchestra budget check --json
+orchestra workflow run --task STORY-001 --gates phase
 ```
 
 The OpenAI adapter reads `OPENAI_API_KEY` from the environment and optionally
@@ -128,10 +129,10 @@ the work and does not want Orchestra to call OpenAI, Anthropic, or another
 vendor API directly:
 
 ```bash
-node bin/orchestra.js runtime adapters --json
-node bin/orchestra.js runtime brief --task STORY-001 --runtime claude-cli
-node bin/orchestra.js runtime delegate-plan --task STORY-001 --runtime claude-cli --roles architect,developer,qa
-node bin/orchestra.js runtime handoff --task STORY-001 --runtime claude-cli --artifact .agent-workflow/runs/STORY-001-runtime-claude-cli-delegation.md
+orchestra runtime adapters --json
+orchestra runtime brief --task STORY-001 --runtime claude-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
 ```
 
 Runtime briefs and delegation packets are written under `.agent-workflow/runs/`

package/docs/setup-agents-bridge.md

@@ -0,0 +1,61 @@
+# setup-agents Bridge
+
+Open Orchestra can import optional `setup-agents` artifacts without making the
+runtime depend on Salesforce-specific setup flows.
+
+## Command
+
+```bash
+orchestra setup-agents import --source .setup-agents
+```
+
+Use `--json` to get a machine-readable report with imported, skipped, and
+conflicted profiles, tasks, evidence references, and handoff references.
+
+## Supported Inputs
+
+The importer reads:
+
+- `.setup-agents/open-orchestra/profiles.json`
+- `.setup-agents/tasks.json`
+- `.setup-agents/tasks.jsonl`
+- `.setup-agents/state/**/*.json`
+- `.setup-agents/state/**/*.jsonl`
+
+Task records may use either sparse legacy fields or enriched delivery fields.
+Supported task fields include:
+
+- `id`, `title`, `summary`
+- `owner`, `ownerRole`, `role`, `profile`, `profileId`
+- `backlogItem`, `backlog`
+- `userStory`, `goal`, `scope`
+- `acceptanceCriteria`
+- `definitionOfReady`, `definitionOfDone`
+- `dependencies`, `dependsOn`
+- `risks`, `assumptions`, `paths`, `files`
+- `testStrategy`
+- `contractVersion`
+- `acceptanceStatus`, `acceptedBy`
+- `evidenceIds`, `evidence`
+- `handoffIds`, `handoffs`
+
+## Mapping Rules
+
+Profile role mappings are read from `profiles.json` when present. Setup role
+IDs such as `setup-agents:qa` are normalized to Orchestra role IDs such as
+`qa`. Unknown owner roles are treated as conflicts during profile import and
+fall back to `developer` for sparse task records.
+
+Imported tasks preserve setup metadata in `task.externalRefs.setupAgents`.
+Evidence and handoff IDs are stored as references there; the importer does not
+copy or mutate the original setup artifacts.
+
+## Idempotency And Conflicts
+
+Re-running the import does not duplicate tasks. If an existing task has the
+same ID, title, and owner role, the task is reported as skipped. If the ID
+matches but title or owner differs, the importer reports a conflict and leaves
+the existing Orchestra task unchanged.
+
+Each import records a `SETUP_AGENTS_IMPORTED` event with summary counts so the
+story-to-evidence trail remains auditable.

package/docs/traceability-flow.md

@@ -0,0 +1,89 @@
+# Story To Release Traceability
+
+Open Orchestra keeps delivery traceability in `.agent-workflow/`. The goal is
+to connect a backlog story to technical work, verification evidence, reviews,
+and release readiness without relying on chat history.
+
+## Product Owner Refinement
+
+Start with a task that has a backlog item, goal, scope, acceptance criteria,
+risks, and test strategy:
+
+```bash
+orchestra task add --id STORY-1 --title "..." --owner product_owner --backlog HU-1 --acceptance "criterion one,criterion two"
+orchestra task update --id STORY-1 --goal "..." --scope "..." --risks "..." --test-strategy "..."
+orchestra readiness --task STORY-1
+```
+
+The task record is the story anchor. Keep acceptance criteria user-visible and
+avoid hiding product requirements in handoff notes.
+
+## Developer Delivery
+
+Before implementation, the developer reads the context bundle and records
+material decisions:
+
+```bash
+orchestra context --task STORY-1 --json
+orchestra decision add --task STORY-1 --owner developer --title "..." --context "..." --decision "..." --consequences "..."
+```
+
+Implementation evidence belongs on the task:
+
+```bash
+orchestra evidence add --task STORY-1 --role developer --type command --summary "unit tests passed" --command "npm test" --exit-code 0
+```
+
+## QA Verification
+
+QA verifies acceptance criteria, regression areas, edge cases, and data setup.
+Browser automation should use Playwright evidence when the behavior is
+user-facing:
+
+```bash
+orchestra playwright plan --task STORY-1
+orchestra playwright evidence --task STORY-1 --kind trace --path test-results/story-1.zip --summary "acceptance flow trace"
+orchestra review --task STORY-1 --role qa --result approve --findings "..." --recommendation "..."
+```
+
+Developer-to-QA handoff should include touched files, commands, known gaps, and
+recommended Playwright coverage.
+
+## Advisory Conversion
+
+Advisory mode stores portable planning artifacts under
+`.agent-workflow/advisory/`. Convert `project-task.json` into a real project
+task only after the target repository and scope are confirmed.
+
+Setup-agents imports preserve external references under
+`task.externalRefs.setupAgents`, including evidence IDs, handoff IDs, acceptance
+status, and contract version.
+
+## Release Readiness
+
+Release readiness composes task readiness, architecture, QA, risk, evidence,
+handoffs, reviews, and locks:
+
+```bash
+orchestra gate --gate release-readiness --task STORY-1
+orchestra release check --json
+orchestra release candidate --version <version> --json
+```
+
+The release manager should only accept unresolved risks when they are recorded
+as explicit reviews, decisions, or release evidence.
+
+## Generated Reference Separation
+
+Generated runtime files such as `AGENTS.md`, `ORCHESTRA.md`, and runtime adapter
+blocks guide agents. Delivery truth remains in `.agent-workflow/` artifacts:
+
+- `tasks.json` for backlog and ownership state.
+- `decisions/` for why choices were made.
+- `handoffs/` for role-to-role transfer.
+- `evidence/` for command, file, screenshot, trace, video, log, or report proof.
+- `reviews/` for approvals, blocks, and accepted risks.
+- `releases/` for release candidate and rollback evidence.
+
+Do not treat generated prompt text as delivery evidence unless it is explicitly
+attached through `orchestra evidence add`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jterrats/open-orchestra",
-  "version": "0.4.2-beta.1",
+  "version": "0.5.0-beta.0",
   "type": "module",
   "bin": {
     "orchestra": "bin/orchestra.js"
@@ -9,10 +9,12 @@
     "build": "tsc && npm run build:web",
     "typecheck": "tsc --noEmit",
     "test": "npm run build && node --test test/**/*.js extensions/**/*.test.cjs",
-    "lint": "eslint . && prettier --check \"{bin,scripts,test,src}/**/*.js\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.json\"",
-    "format": "prettier --write \"{bin,scripts,test,src}/**/*.js\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.json\"",
+    "test:e2e": "npm run 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}\"",
     "secret-scan": "node scripts/secret-scan.js",
-    "validate:workflow": "sh -c 'test ! -d .agent-workflow || (npm run build && node bin/orchestra.js validate)'",
+    "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",
@@ -23,15 +25,15 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@playwright/test": "^1.59.1",
     "@types/node": "^25.6.0",
+    "chart.js": "^4.5.1",
     "esbuild": "^0.28.0",
     "eslint": "^10.2.1",
     "prettier": "^3.8.3",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.0",
-    "chart.js": "^4.5.1"
+    "typescript-eslint": "^8.59.0"
   },
-  "dependencies": {},
   "description": "Local control plane for AI-assisted development orchestration, evidence gates, and agent workflows.",
   "repository": {
     "type": "git",