# Persona Workflows Use these paths when you want to operate Open Orchestra by role instead of learning the full command catalog first. Commands assume the installed CLI form: `orchestra`. ## First Visible Value Goal: complete one local workflow run and preview release readiness before learning every role-specific artifact. Commands: ```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 ``` Expected artifacts: - `.agent-workflow/tasks.json` contains `DEMO-001`. - `.agent-workflow/workflow-runs.jsonl` contains the completed lifecycle. - Release candidate dry-run output shows what is ready and what evidence is still missing. Recovery: - Run `orchestra health --json` if local tools are missing. - Use `orchestra workflow runs` to find a paused or failed run. - Move to the production paths below when the story needs human gates, explicit sizing, command evidence, QA review, and release readiness approval. ## Product Owner Refinement Goal: turn a backlog item into a task that is ready for architecture and delivery. Commands: ```bash orchestra health --json orchestra task add --id STORY-001 --title "..." --owner product_owner \ --paths "src,docs,test" --goal "..." --acceptance "..." \ --risks "..." --test-strategy "..." orchestra github sync --issue 123 --task STORY-001 --comment --dry-run --json orchestra context --task STORY-001 ``` Expected artifacts: - `.agent-workflow/tasks.json` task entry with backlog item, acceptance criteria, assumptions, risks, paths, and test strategy. - GitHub sync dry-run or comment evidence when using GitHub issues. - Context output showing memory, missing artifacts, and selected workflow. Common blockers: - Missing acceptance criteria or test strategy. - GitHub CLI unavailable in local shell. - Issue tracker is not GitHub. Recovery: - Add missing readiness fields with `orchestra task update --id STORY-001 ...`. - Use `orchestra github sync --transport mcp-skill` only as a runtime-adapter boundary; tracker MCP skills for GitHub, Jira, Bitbucket, GitLab, or custom trackers must inject equivalent issue/comment/close operations. - Continue locally with task metadata when tracker sync is unavailable. Related docs: [first-use flow](../README.md#quick-start), [GitHub sync](orchestra-mvp.md), and [memory hooks](orchestra-mvp.md). ## Developer Execution Goal: implement a scoped task with role handoffs, evidence, and workflow gates. Commands: ```bash orchestra delegation decide --task STORY-001 orchestra workflow run --task STORY-001 --gates phase orchestra decision add --task STORY-001 --owner architect \ --title "Story sizing" --decision "m 3 points" \ --context "..." --consequences "..." --status accepted orchestra memory hook --point before_implementation --task STORY-001 \ --role developer --json orchestra evidence add --task STORY-001 --role developer --type command \ --summary "npm run precommit passed" --command "npm run precommit" \ --exit-code 0 ``` Expected artifacts: - Workflow run records in `.agent-workflow/workflow-runs.jsonl`. - Decisions and handoffs under `.agent-workflow/decisions/` and `.agent-workflow/handoffs/`. - Command evidence under `.agent-workflow/evidence/`. Common blockers: - Architect sizing missing before development. - Active locks on overlapping paths. - Context budget too high or memory output too broad. Recovery: - Record the sizing decision printed by the workflow failure. - Inspect conflicts with `orchestra graph plan --json`. - Query role-scoped memory with `orchestra memory query --role developer`. Related docs: [autonomous workflow](autonomous-workflow.md), [runtime flow](runtime-llm-flow.md), and [memory governance](orchestra-mvp.md). ## QA Validation Goal: prove acceptance criteria with traceable evidence and release-ready coverage. Commands: ```bash orchestra playwright plan --task STORY-001 orchestra playwright evidence --task STORY-001 --kind screenshot \ --summary "Browser AC passed" --path path/to/screenshot.png orchestra review --task STORY-001 --role qa --result approve \ --findings "AC covered" --recommendation "Release handoff approved" orchestra gate --gate qa-release --task STORY-001 ``` Expected artifacts: - QA review in `.agent-workflow/reviews/`. - Unit, integration, manual, or Playwright evidence mapped to acceptance criteria. - QA gate result showing no missing plan, execution status, or QA evidence. Common blockers: - Browser/UI AC has only report evidence and no Playwright artifact. - QA review blocks are unresolved. - Evidence summary does not identify the AC it covers. Recovery: - Attach screenshot, trace, or video evidence for browser criteria. - Resolve blocker reviews with a new QA review after fixes. - Use evidence summaries that name the acceptance criterion or say "covers all acceptance criteria." Related docs: [release readiness](orchestra-mvp.md) and [Playwright evidence](orchestra-mvp.md). ## Tech Lead Oversight Goal: keep parallel work coordinated and reviewable. Commands: ```bash orchestra graph plan --json orchestra review --task STORY-001 --role tech_lead --result approve \ --findings "Diff and tests reviewed" --recommendation "Proceed" orchestra pr-summary --task STORY-001 orchestra commands manifest --json ``` Expected artifacts: - Graph plan with ready, blocked, locked, and dependency-ready tasks. - Tech lead review artifact with severity and recommendation. - PR summary with evidence, risks, and remaining gaps. Common blockers: - Multiple agents edit the same path without locks. - Command behavior is duplicated outside the manifest. - PR lacks command evidence or reviewer context. Recovery: - Split work by stable path boundaries and record locks. - Check the manifest before adding commands. - Add missing evidence and rerun `orchestra pr-summary --task STORY-001`. Related docs: [command contracts](command-contracts.md), [traceability](traceability-flow.md), and [runtime adapters](runtime-adapters.md). ## Release Management Goal: decide whether a story or candidate release can ship. Commands: ```bash orchestra release check --json orchestra release evidence --kind smoke --summary "smoke passed" orchestra release evidence --kind rollback --summary "rollback verified" orchestra release evidence --kind post-release --summary "post-release smoke passed" orchestra release evidence --kind release-notes --summary "release notes published" orchestra gate --gate release-readiness --task STORY-001 orchestra release candidate --version 0.5.0-beta.0 --json ``` Expected artifacts: - Release check JSON with acceptance coverage, blockers, locks, smoke, and rollback gaps. - Smoke and rollback evidence events. - Candidate release plan under `.agent-workflow/releases/`. Common blockers: - Uncovered acceptance criteria. - Active locks or blocker reviews. - Missing smoke or rollback evidence. - Dirty working tree during release check. Recovery: - Attach required evidence or record an accepted risk on the task. - Resolve locks and blocking reviews. - Run `orchestra upgrade --smoke --json` after installing a new package version. Related docs: [upgrade dogfooding](orchestra-mvp.md), [package naming](package-naming.md), and [release readiness](orchestra-mvp.md). ## Technical Writer Review Goal: keep public documentation, site copy, command examples, release notes, and help content accurate for the intended audience. Commands: ```bash orchestra workflow phase-plan --task STORY-001 --json orchestra doc-sync audit --task STORY-001 --json orchestra review --task STORY-001 --role technical_writer --result approve \ --findings "Docs, links, commands, and generated site content reviewed" \ --recommendation "Documentation ready for release" ``` Expected artifacts: - Technical Writer review in `.agent-workflow/reviews/`. - Documentation diff or link evidence for updated docs, README, changelog, release notes, runbooks, help content, or public site copy. - Site QA evidence when generated site content, diagrams, visible copy, or responsive layout changes. Common blockers: - Public site copy is hardcoded in React instead of generated from `docs/site-manifest.json`. - Command examples were not validated against the CLI, command manifest, or build output. - `docs/architecture.md` and `site/public/architecture.mmd` describe different diagrams. Recovery: - Update the source markdown or manifest, then run `npm run site:content`. - Run `npm run site:build` and capture screenshots for visible site changes. - Use `orchestra doc-sync audit --task --json` to find missing documentation coverage. Related docs: [public site content workflow](site-content-workflow.md), [adoption guide](adoption-guide.md), and [release matrix](release-test-matrix.md). ## Docs Review Checklist Before release, verify: - Persona paths use `orchestra`, not local `node bin/orchestra.js`, unless the section is explicitly about repository development. - Package references use `@jterrats/open-orchestra`. - Links cover first-use onboarding, web console, memory, GitHub sync, release readiness, and upgrade dogfooding. - Commands list expected artifacts, common blockers, and recovery steps. - Site copy reflects implemented capabilities, not planned-only features.