feat(qa): Playwright-first browser QA, named targets, /orc:explain

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "orc",
       "source": "./orc",
-      "description": "81 curated skills (incl. workspace-mode for cross-repo flows), 30 composite slash commands, 14 specialist subagents with per-agent model + reasoning-effort tuning, and 10 hook scripts that quietly enforce discipline (confirm-to-commit on protected branches, destructive-git gating, no AI-attribution trailers in commits/PRs, dependency pre-flight, iron rules injected at session start). Covers the whole SDLC — including post-PR: CI diagnosis, releases, dependency audits, live incident response. Drives the senior-IC loop end-to-end via /orc:flow — workspace-aware: from a parent dir with multiple sibling repos, one flow spans them all with N linked PRs."
+      "description": "84 curated skills (incl. workspace-mode for cross-repo flows), 31 composite slash commands, 14 specialist subagents with per-agent model + reasoning-effort tuning, and 10 hook scripts that quietly enforce discipline (confirm-to-commit on protected branches, destructive-git gating, no AI-attribution trailers in commits/PRs, dependency pre-flight, iron rules injected at session start). Covers the whole SDLC — including post-PR: CI diagnosis, releases, dependency audits, live incident response. Drives the senior-IC loop end-to-end via /orc:flow — workspace-aware: from a parent dir with multiple sibling repos, one flow spans them all with N linked PRs."
     }
   ]
 }

.github/workflows/validate.yml

@@ -78,6 +78,21 @@ jobs:
       - name: QA report fixtures (orc-report json/html)
         run: bash scripts/ci/verify-report.sh
 
+      - name: Target registry fixtures (orc-targets)
+        run: bash scripts/ci/verify-targets.sh
+
+      - name: Playwright scaffold fixtures (orc-playwright)
+        run: bash scripts/ci/verify-playwright-env.sh
+
+      - name: QA video fixtures (orc-qa-video)
+        run: bash scripts/ci/verify-qa-video.sh
+
+      - name: Explainer toolchain fixtures (orc-explain)
+        run: bash scripts/ci/verify-explain.sh
+
+      - name: PR size budget exclusions
+        run: bash scripts/ci/verify-pr-size.sh
+
       - name: statusline render fixtures
         run: bash scripts/ci/verify-statusline.sh
 

README.md

@@ -36,14 +36,14 @@
 </p>
 
 <p align="center">
-  <code>81 skills</code> &nbsp;·&nbsp; <code>30 commands</code> &nbsp;·&nbsp;
+  <code>84 skills</code> &nbsp;·&nbsp; <code>31 commands</code> &nbsp;·&nbsp;
   <code>14 agents</code> &nbsp;·&nbsp; <code>9 hooks</code> &nbsp;·&nbsp;
   <code>0 telemetry</code> &nbsp;·&nbsp; <code>MIT</code>
 </p>
 
 ---
 
-`orc` is a full-SDLC workflow plugin for Claude Code: **81 curated skills, 30 composite slash commands, 14 specialist subagents, and 10 hook scripts** that quietly enforce discipline (no commits to `main`, no AI-attribution trailers, destructive git commands gated, a dependency pre-flight, core rules injected at every session start). One umbrella command — **`/orc:flow`** — drives the full feature lifecycle from "I want to do X" to "PR merged", with the `orc-implementer` agent writing the code slice-by-slice in between — and the lifecycle no longer stops at PR-open: `/orc:ci`, `/orc:release`, `/orc:deps`, and `/orc:incident` cover what happens after.
+`orc` is a full-SDLC workflow plugin for Claude Code: **84 curated skills, 31 composite slash commands, 14 specialist subagents, and 10 hook scripts** that quietly enforce discipline (no commits to `main`, no AI-attribution trailers, destructive git commands gated, a dependency pre-flight, core rules injected at every session start). One umbrella command — **`/orc:flow`** — drives the full feature lifecycle from "I want to do X" to "PR merged", with the `orc-implementer` agent writing the code slice-by-slice in between — and the lifecycle no longer stops at PR-open: `/orc:ci`, `/orc:release`, `/orc:deps`, and `/orc:incident` cover what happens after.
 
 It exists for one reason: every time a senior developer sits down to work, they should already know how the next hour goes — write the plan, watch the test fail, fix the cause (not the symptom), verify with evidence, ship the PR. orc encodes that loop.
 
@@ -123,7 +123,7 @@ Claude Code loads every skill/command/agent **description** at session start (th
 |------|--------------|
 | [docs/install.md](./docs/install.md) | Step-by-step install with verification checkpoints, marketplace-only path, requirements table |
 | [docs/commands.md](./docs/commands.md) | Full command table, the specialist agents, the skill library, the CLI reference |
-| [docs/examples](./docs/examples/README.md) | 18 scenario walk-throughs — start here for usage |
+| [docs/examples](./docs/examples/README.md) | 19 scenario walk-throughs — start here for usage |
 | [docs/configuration.md](./docs/configuration.md) | Plugin settings, env vars, statusline tuning |
 | [docs/safety.md](./docs/safety.md) | The safety case in depth + FAQ |
 | [docs/architecture.md](./docs/architecture.md) | Why the layout is what it is; hooks, state, and the `.orc/` lifecycle |

cli/internal/deps/tools.json

@@ -55,7 +55,7 @@
     {
       "name": "agent-browser",
       "tier": "recommended",
-      "usedBy": "`/orc:qa` (web mode — required for browser-driven QA evidence)",
+      "usedBy": "`/orc:qa` fallback driver when Node/Playwright is unavailable; `/orc:evidence`",
       "hints": {
         "macos": "brew install agent-browser && agent-browser install",
         "default": "npm install -g agent-browser && agent-browser install"
@@ -153,7 +153,7 @@
     {
       "name": "ffmpeg",
       "tier": "recommended",
-      "usedBy": "`/orc:qa`, `/orc:evidence` (motion evidence — agent-browser's `record` wraps ffmpeg; without it a headless QA run captures stills only)",
+      "usedBy": "`/orc:qa` (stitched QA video), `/orc:explain` (explainer render), agent-browser `record` — title cards and captions need an ffmpeg build with libfreetype (`brew install ffmpeg` has it; minimal builds don't)",
       "hints": {
         "macos": "brew install ffmpeg",
         "debian": "sudo apt-get install -y ffmpeg",

docs/architecture.md

@@ -9,8 +9,8 @@
 ```
 orc/                               # the plugin
 ├── .claude-plugin/plugin.json     # manifest — what Claude Code reads to discover the plugin
-├── skills/                        # 81 skills, namespaced /orc:<name>
-├── commands/                      # 30 composite slash commands /orc:<cmd> (incl. /orc:flow umbrella)
+├── skills/                        # 84 skills, namespaced /orc:<name>
+├── commands/                      # 31 composite slash commands /orc:<cmd> (incl. /orc:flow umbrella)
 ├── agents/                        # 14 specialist subagents (orc-<role>)
 ├── hooks/                         # SessionStart + PreToolUse(Bash) + PostToolUse + PreCompact + WorktreeCreate/Remove
 │   └── mod/                       # the orc mod (register.ts + tests) — in-process hooks, Claude Code 2.1.287+
@@ -162,7 +162,7 @@ Plus the doc-authoring family for senior/architect practice: `adr-writing` (Arch
 
 orc borrows compozy's session-state idea, hook layout, and YAML-frontmatter conventions. It diverges in two places:
 1. Workspace state is **hidden + gitignored** (`.orc/`) instead of committed (`compozy/`). orc is a personal plugin; nothing needs sharing.
-2. Command surface covers the full SDLC (30 commands, all composing the same plan → debug → verify → ship spine, now extended past PR-open with ci/release/deps/incident), with explicit web-QA evidence as a first-class concern — including the environment it runs against: `/orc:qa` and `/orc:flow` provision a Docker dev environment via `orc-env-provisioner` before browser QA (`orc:env-provisioning` skill; `/orc:env` standalone).
+2. Command surface covers the full SDLC (31 commands, all composing the same plan → debug → verify → ship spine, now extended past PR-open with ci/release/deps/incident), with explicit web-QA evidence as a first-class concern — including the environment it runs against: `/orc:qa` and `/orc:flow` provision a Docker dev environment via `orc-env-provisioner` before browser QA (`orc:env-provisioning` skill; `/orc:env` standalone).
 
 ## See also
 

docs/commands.md

@@ -1,16 +1,16 @@
 # What orc can do
 
-The full catalog: every slash command, the specialist agents behind them, the skill library underneath, and the CLI that installs it all. Not sure where to start? The [examples index](examples/README.md) maps 18 real scenarios to the command that handles each.
+The full catalog: every slash command, the specialist agents behind them, the skill library underneath, and the CLI that installs it all. Not sure where to start? The [examples index](examples/README.md) maps 19 real scenarios to the command that handles each.
 
-## Commands (30)
+## Commands (31)
 
 | Command | Purpose |
 |---------|---------|
 | **`/orc:flow`** | **Recommended entry point.** Drives the full lifecycle (plan → start → implement → QA → ship → address → cleanup) with a gate at every phase. Resumable from any phase. |
 | `/orc:plan` | Plan a feature/refactor; writes a TDD-shaped plan to `.orc/<branch>/files/` |
 | `/orc:start` | Worktree + plan + first failing test (TDD red light) |
 | `/orc:debug` | Root-cause investigation, then fix with TDD; never papers over |
-| `/orc:qa` | Pre-PR quality gate; for web changes, full browser QA with screenshots/snapshot/HAR/steps |
+| `/orc:qa` | Pre-PR quality gate; web changes run Playwright-first browser QA against a named target (`--target`) with a stitched step-tagged video, traces, and committed e2e specs/tests |
 | `/orc:env` | Provision a containerized dev environment; `up`/`status`/`down`; reused across QA runs |
 | `/orc:code-review` | Review someone else's open PR; terse, signal-only output |
 | `/orc:address` | Answer reviewer comments on YOUR PR; parallel code-fixer + reply-drafter |
@@ -25,6 +25,7 @@ The full catalog: every slash command, the specialist agents behind them, the sk
 | `/orc:jira` | Manage Jira tickets via `acli`; bind/unbind a ticket to the current session |
 | `/orc:jira-breakdown` | Build a Jira Epic (micro-PRD) → Stories → concurrency-sliced Tasks from a brief or PRD |
 | `/orc:evidence` | Collect browser evidence scoped to a ticket, then upload or keep local |
+| `/orc:explain` | Narrated walkthrough video of a QA packet — Playwright demo clips + animate graphics + local kokoro voice. Graphic segments are authored: orc writes the piece metadata and brief, the session writes `src/scenes.js` per the notes in `orc/lib/explain/animate.lock` (pinned animate commit), then renders with `ORC_ANIMATE_RENDER=1`. |
 | `/orc:postmortem` | Author a blameless incident postmortem; files P0 items as tracker issues |
 | `/orc:ci` | Watch + diagnose CI after PR-open; classified failures routed to `orc-code-fixer` |
 | `/orc:incident` | Live incident triage — Sentry intake, mitigate-vs-root-cause gate, UTC timeline |
@@ -39,9 +40,9 @@ The full catalog: every slash command, the specialist agents behind them, the sk
 
 `orc-implementer` (writes code slice-by-slice), `orc-debug-investigator`, `orc-test-author`, `orc-code-fixer`, `orc-pr-reviewer`, `orc-security-reviewer`, `orc-ci-investigator`, `orc-qa-validator`, `orc-env-provisioner`, `orc-prd-analyzer`, `orc-refactor-architect`, `orc-jira-architect`, `orc-reply-drafter`, `orc-stack-analyzer` — each a read-only investigator or a scoped executor, dispatched by the commands above. Every agent pins both a `model` (haiku for mechanical work, sonnet for senior-dev execution, opus for deep investigation) and a reasoning `effort` matched to its task shape.
 
-## Skills (81)
+## Skills (84)
 
-Under the commands and agents sit 81 curated skills — reusable, progressively-disclosed playbooks the model pulls in on demand: process doctrine (`tdd`, `systematic-debugging`, `verification-before-completion`, `grilling`, `codebase-design`, `domain-modeling`), stack packs (Next.js, NestJS, PostgreSQL, SwiftUI, Tailwind, Turborepo, …), authoring guides (PRD/TRD/ADR/RFC/postmortem), and the `orc:map` router when you're not sure which to reach for. Fifteen are vendored or merged from [mattpocock/skills](https://github.com/mattpocock/skills) and other MIT sources with full provenance ([THIRD-PARTY-LICENSES.md](../THIRD-PARTY-LICENSES.md)); their descriptions are deliberately differentiated so co-installing the originals doesn't double-trigger. Each skill is a thin index that loads its detail only when invoked, so they cost almost nothing until used. **Total: 81 skills.**
+Under the commands and agents sit 84 curated skills — reusable, progressively-disclosed playbooks the model pulls in on demand: process doctrine (`tdd`, `systematic-debugging`, `verification-before-completion`, `grilling`, `codebase-design`, `domain-modeling`), stack packs (Next.js, NestJS, PostgreSQL, SwiftUI, Tailwind, Turborepo, …), authoring guides (PRD/TRD/ADR/RFC/postmortem), and the `orc:map` router when you're not sure which to reach for. Fifteen are vendored or merged from [mattpocock/skills](https://github.com/mattpocock/skills) and other MIT sources with full provenance ([THIRD-PARTY-LICENSES.md](../THIRD-PARTY-LICENSES.md)); their descriptions are deliberately differentiated so co-installing the originals doesn't double-trigger. Each skill is a thin index that loads its detail only when invoked, so they cost almost nothing until used. **Total: 84 skills.**
 
 ## The orc CLI
 

docs/configuration.md

@@ -16,6 +16,8 @@ Prompted at plugin enable time (re-run via `/plugin`); exported to hooks and lib
 | `statusline_context_reserve` | `0` | 0–50. When >0, the context percentage is normalized against this reserved slice (e.g. your auto-compact reserve) and rendered with a `~` prefix. `0` shows the raw payload percentage. |
 | `mod_enabled` | `true` | Load the orc mod (`hooks/mod/`, Claude Code 2.1.287+): in-process event hooks and UI layered on the bash hooks. `false` keeps orc on its bash hooks only — the guardrails are identical either way. |
 | `model_profile` | `balanced` | Which model orc agents run on when a dispatch names none (needs the orc mod): `balanced` (each agent's frontmatter), `quality` (investigator on `best` — Fable where available, else Opus — reviewers on Opus), `economy` (Opus-tier agents on Sonnet). An explicit per-dispatch model always wins; the `/orc` cockpit's Model profile select settles a per-branch override (`modelProfile` decision) that wins over this value. |
+| `explainer_style` | `isometric` | animate motion-graphics style for `/orc:explain` segments: cut-paper, crosshatch, riso, sketchbook, math, pixel, isometric. |
+| `explainer_voice` | `af_heart` | kokoro-js voice id for `/orc:explain` narration (local TTS, no key). `af_heart` = English; `pf_dora` / `pm_alex` = Brazilian Portuguese. |
 | `alerts_sound` | `false` | A short chime when the orc mod's CI watcher sees a linked PR turn red or green. |
 
 ## Environment variables
@@ -25,6 +27,12 @@ Prompted at plugin enable time (re-run via `/plugin`); exported to hooks and lib
 | `ORC_SKIP_TOOL_CHECK=1` | Suppress the SessionStart tool-check callout when a recommended dependency is intentionally missing. |
 | `ORC_ALLOW_AI_ATTRIBUTION=1` | Allow AI-attribution trailers in commits/PR bodies. The PreToolUse hook refuses them by default (iron rule #5). Set only with explicit user consent. |
 | `ORC_ALLOW_DESTRUCTIVE_GIT=1` | Skip the confirm prompt on `git reset --hard`, `git clean -f`, `git branch -D`, `git push --force`. |
+| `ORC_TARGETS_OP_BIN` | 1Password CLI binary used by `orc-targets resolve` for `op://` credential references. Defaults to `op`. |
+| `ORC_QA_USER` | Which named target user the Playwright `setup` project logs in as. |
+| `ORC_PW_OUTPUT_DIR` | Playwright output directory; the `playwright-qa` skill sets it to `<qa-dir>/pw`. |
+| `ORC_EXPLAIN_VOICE` | kokoro-js voice id for `orc-explain narrate`; overrides the `explainer_voice` setting. |
+| `ORC_ANIMATE_ROOT` | Path to the installed animate plugin used by `orc-explain graphics`. |
+| `ORC_ANIMATE_RENDER` | `1` builds/exports authored animate pieces; unset renders fallback title cards. |
 | `ORC_JIRA_PR_KEYWORD` | PR-body trailer keyword used by `/orc:ship` when the session has a bound Jira ticket. Defaults to `Resolves`. |
 
 The `orc config` CLI edits these tunables (`pr_size_budget`, `protected_branches`, `skip_tool_check`, `allow_ai_attribution`, `jira_pr_keyword`) as `ORC_*` variables in `settings.json`.

docs/examples/10-web-qa-before-shipping.md

@@ -234,7 +234,7 @@ Then: `/orc:ship` — and the PR body links to `qa/steps.md` so reviewers can ve
 - **Multiple devices/breakpoints** — repeat the golden path with `agent-browser set viewport <w> <h>` for each. Save screenshots per breakpoint (`screenshot-01a-mobile-loaded.png`, `screenshot-01b-desktop-loaded.png`).
 - **Watch the QA live** — pick the Claude-in-Chrome driver at the gate (or `--driver chrome`). The walk runs inline in your real browser (real sessions, cookies, extensions), narrated step by step; the evidence packet swaps per-step screenshots for a `gif_creator` recording and the HAR for a distilled `network-summary.md`. Acceptance scoring is identical — each criterion anchors to a numbered step in `steps.md` instead of its own PNG.
 - **Behind a feature flag** — boot the app with the flag enabled, document the flag state at the top of `steps.md`.
-- **App not yet boot-able locally** — ask the user for a deployed preview URL (Vercel preview, staging, etc.). Don't fake QA against the prod app.
+- **App not yet boot-able locally** — use `--target <name>` (`orc:qa-targets`) to point QA at a registered staging or preview target. Never fake QA against prod.
 
 ## Iron rules in play