Run critic rounds as real multi-agent Workflows (not simulated critics)

.claude/commands/critic-round.md

@@ -1,46 +1,35 @@
 ---
-description: Read-only multi-agent critic review of the current localhost app state — returns a severity-classified findings matrix, makes no code changes. Use when you want an assessment without implementing.
+description: Run the multi-agent critic round as a deterministic Workflow — critics fan out as parallel subagents (own context each), each blocker/important finding is adversarially verified by a separate skeptic, then a synthesized severity matrix is returned. Read-only; changes no code.
 argument-hint: [focus, e.g. "checkout flow on localhost"]
 ---
 
-Run a multi-agent critic review of the current local web app state.
+Run a **genuine multi-agent critic round** — not a single agent simulating critics.
+Use the **Workflow tool** so each critic runs as its own subagent in its own context
+and every blocker/important finding is verified by a *separate* skeptic.
 
 Focus:
 $ARGUMENTS
 
-Use these critics:
-
-1. First-Time User Critic
-2. UX Flow Critic
-3. Designer Critic
-4. Artistic Direction Critic
-5. Frontend Architecture Critic
-6. QA / E2E Critic
-7. Accessibility Critic
-8. Performance Critic
-9. Security Critic
-10. Regression Critic
-
-Procedure:
-
-1. Inspect relevant code.
-2. Start or reuse localhost.
-3. Open the relevant page in Chrome or Playwright MCP.
-4. Test the flow as a real user.
-5. Check console errors.
-6. Check failed network requests.
-7. Ask each critic to independently review.
-8. Return a critic matrix.
-
-Output format:
-
-| Critic | Severity | Finding | Evidence | Recommended action |
-|---|---|---|---|---|
-
-Classify severity:
-
-- blocker: must fix before task is complete
-- important: should fix in this task if related
-- nice-to-have: record only, do not fix unless asked
-
-Do not edit files unless explicitly asked.
+## Procedure
+1. Make sure context exists for the critics: confirm `CLAUDE.md` and (if a UI flow
+   is in scope) that localhost is running for the browser-driven critics.
+2. **Invoke the Workflow tool** with the predefined critic-panel workflow:
+   - `scriptPath: .claude/workflows/critic-panel.js`
+   - `args: { "focus": "$ARGUMENTS" }`
+   This command explicitly opts into multi-agent orchestration — calling Workflow
+   here is expected.
+3. The workflow returns `{ focus, counts, confirmed, niceToHaves, refuted }`.
+   Render `confirmed` as the critic matrix and list `niceToHaves` separately:
+
+   | Critic | Severity | Finding | Evidence | Recommended action |
+   |---|---|---|---|---|
+
+4. Note any `refuted` findings (a skeptic could not substantiate them) so they are
+   not actioned. Do **not** edit files — this is review only.
+
+## Notes
+- This is the heavier, deterministic path (the workflow spawns ~10 critic agents +
+  one verifier per blocker/important finding). That is intended: real independent
+  review, not one context role-playing ten critics.
+- Other commands (`/multi-agent-dev`, `/multi-agent-e2e`, `/qa-pass`) reuse this same
+  workflow for their critic rounds.

.claude/commands/multi-agent-dev.md

@@ -8,53 +8,37 @@ Run a full multi-agent development loop for this local web app.
 User task:
 $ARGUMENTS
 
-You are the Lead Agent.
-
-You must use the following critic agents before implementation:
-
-1. First-Time User Critic
-2. UX Flow Critic
-3. Designer Critic
-4. Artistic Direction Critic
-5. Frontend Architecture Critic
-6. QA / E2E Critic
-7. Accessibility Critic
-8. Performance Critic
-9. Security Critic
-10. Regression Critic
+You are the Lead Agent. The critic rounds run as a **deterministic multi-agent
+Workflow** (critics fan out as parallel subagents in their own contexts; each
+blocker/important finding is verified by a separate skeptic) — **not** one agent
+simulating critics. Invoking the Workflow tool here is expected (this command opts
+into multi-agent orchestration).
 
 Procedure:
 
-1. Read CLAUDE.md.
-2. Read package.json.
-3. Inspect the relevant routes, components, API handlers, tests, and styles.
-4. Start or reuse the local dev server.
-5. Open the relevant localhost page using Chrome or Playwright MCP.
-6. Observe the current behavior.
-7. Run the critic round before implementation.
-
-For each critic, produce:
-
-- severity: blocker / important / nice-to-have
-- finding
-- evidence
-- recommended fix
-
-Then:
-
-8. Synthesize findings as Lead Agent.
-9. Choose the smallest safe implementation plan.
-10. Implement only blockers and important issues directly related to the task.
-11. Run the smallest relevant automated checks first.
-12. Verify in browser on localhost.
-13. Check console errors.
-14. Check failed network requests.
-15. Add or update Playwright E2E tests for the verified flow.
-16. Run relevant E2E tests.
-17. Run typecheck, lint, unit tests, and build if appropriate.
-18. Run a second critic round after implementation.
-19. Fix remaining blockers.
-20. Report final evidence.
+1. Read CLAUDE.md and package.json.
+2. Inspect the relevant routes, components, API handlers, tests, and styles.
+3. Start or reuse the local dev server; open the relevant localhost page (Chrome/
+   Playwright MCP) and observe current behavior.
+4. **Pre-implementation critic round** — invoke the Workflow tool with
+   `scriptPath: .claude/workflows/critic-panel.js`,
+   `args: { "focus": "$ARGUMENTS (current behavior + changed files)" }`.
+   Render the returned `confirmed` findings as the critic matrix; record
+   `niceToHaves`; ignore `refuted`.
+5. As Lead Agent, choose the smallest safe plan from the confirmed blockers +
+   directly-related important findings.
+6. Implement only those. Keep the **maker/checker split**: implementation is your
+   pass; the post-implementation workflow below is the independent checker.
+7. Run the smallest relevant automated checks first.
+8. Verify in browser on localhost; check console errors and failed network requests.
+9. Add or update Playwright E2E tests for the verified flow; run them.
+10. Run typecheck, lint, unit tests, and build if appropriate.
+11. **Post-implementation critic round** — invoke the same Workflow again with
+    `args.focus` set to the changed flow and `args.priorEvidence` set to what you
+    already gathered (git diff summary + test/lint/build results + browser/console
+    findings) so the critics verify against it instead of re-running everything.
+    Fix any remaining confirmed blockers (re-run the workflow until none remain).
+12. Report final evidence.
 
 Never mark complete unless:
 

.claude/commands/multi-agent-e2e.md

@@ -3,40 +3,27 @@ description: Design and run Playwright E2E tests for a user flow via a critic wo
 argument-hint: [target flow, e.g. "onboarding"]
 ---
 
-Design and run E2E tests using a multi-agent critic workflow.
+Design and run E2E tests using a **deterministic multi-agent Workflow** (the critic
+panel runs as parallel subagents in their own contexts) — not one agent simulating
+critics.
 
 Target flow:
 $ARGUMENTS
 
-Roles:
-
-1. QA / E2E Critic
-   - Defines critical paths and edge cases.
-
-2. First-Time User Critic
-   - Defines what a new user would try first.
-
-3. UX Flow Critic
-   - Defines success, failure, loading, and recovery states.
-
-4. Accessibility Critic
-   - Defines keyboard and screen-reader relevant checks.
-
-5. Regression Critic
-   - Identifies existing flows that could break.
-
 Procedure:
 
-1. Inspect existing Playwright tests.
-2. Inspect app routes and components.
-3. Start or reuse localhost.
-4. Manually verify the target flow in browser.
-5. Draft E2E test cases from critic findings.
-6. Implement Playwright tests.
-7. Run the specific E2E tests.
-8. Fix test or app failures, but do not weaken assertions.
-9. Run browser verification again.
-10. Report evidence.
+1. Inspect existing Playwright tests, app routes, and components.
+2. Start or reuse localhost; manually verify the target flow in browser.
+3. **Enumerate test cases via a Workflow** — invoke the Workflow tool with
+   `scriptPath: .claude/workflows/e2e-design.js`, `args: { "flow": "$ARGUMENTS" }`.
+   One agent per path category (happy, failure, edge, accessibility, regression)
+   enumerates concrete cases in its own context; results are deduped. (Invoking
+   Workflow here is expected.) It returns `{ flow, count, cases }`.
+4. Implement Playwright tests from the returned `cases` (cover the happy path + at
+   least one failure/edge path); run the specific specs.
+5. Fix test or app failures, but do not weaken assertions.
+6. Run browser verification again.
+7. Report evidence.
 
 Required output:
 

.claude/commands/qa-pass.md

@@ -24,13 +24,13 @@ Checklist:
     - buttons have accessible names
     - forms have labels
     - keyboard navigation works for critical flow
-12. Run a post-implementation critic round using:
-    - First-Time User Critic
-    - UX Flow Critic
-    - Designer Critic
-    - QA / E2E Critic
-    - Accessibility Critic
-    - Regression Critic
-13. Report blockers, non-blockers, and recommended next actions.
+12. Run a **post-implementation critic round as a Workflow** — invoke the Workflow
+    tool with `scriptPath: .claude/workflows/critic-panel.js` and
+    `args: { "focus": "the changed flows for $ARGUMENTS", "priorEvidence": "<git diff summary + the typecheck/lint/unit/build/E2E results + a11y/browser findings from steps 2-11>" }`.
+    The critics run as parallel subagents and verify against that evidence; each
+    blocker/important finding is checked by a separate skeptic (no single agent
+    simulating the panel).
+13. Report the workflow's `confirmed` blockers/non-blockers and recommended next
+    actions.
 
 Never mark as complete if build, tests, or critical browser flow fails.

.claude/commands/scan-project-docs.md

@@ -38,8 +38,15 @@ Procedure:
    pile stories into a single file.
 6. Split large stories into independently testable stories.
 7. Add measurable acceptance criteria.
-8. Search the codebase for implementation evidence.
-9. Search the test suite for unit, integration, and E2E evidence.
+8. **Gather evidence in parallel via a Workflow** — once you have the story list,
+   invoke the Workflow tool with `scriptPath: .claude/workflows/scan-docs.js` and
+   `args: { "stories": [ {id, title, source, acceptanceCriteria}, ... ] }`. It
+   pipelines each story through an evidence-gathering agent (searches code + tests)
+   and a *separate* status-verifier agent (evidence-based status, no overclaiming),
+   returning one record per story. This is real multi-agent orchestration, not one
+   agent judging every story in a single context. (Invoking Workflow here is expected.)
+9. Use the returned records as the source of truth for status; do browser
+   verification yourself where it raises a status to `Browser verified`/`Done`.
 10. Start or reuse localhost when browser verification is possible.
 11. Open relevant pages using Chrome or Playwright MCP.
 12. Verify implemented user flows in browser when possible.

.claude/commands/story-gap-analysis.md

@@ -13,27 +13,21 @@ the topic pages relevant to the gaps you're assessing (e.g. `topics/testing.md`,
 `topics/build-and-verify.md`) so "tested / not tested" and "edge cases" judgments
 reflect the project's real conventions.
 
-Produce:
-
-1. Requirements found in docs but not implemented.
-2. Implemented features not described in docs.
-3. Stories implemented but not unit-tested.
-4. Stories implemented but not E2E-tested.
-5. Stories E2E-tested but missing important edge cases.
-6. Stories that work functionally but fail UX/design/artistic direction review.
-7. Ambiguous or contradictory requirements.
-8. Recommended next implementation order.
-
-Use critic agents:
-
-- Product Requirements Critic
-- Code Evidence Critic
-- Unit Test Evidence Critic
-- E2E Test Evidence Critic
-- UX / First-Time User Critic
-- Designer Critic
-- Artistic Direction Critic
-- Regression Critic
-- Documentation Consistency Critic
-
-Do not edit files unless explicitly asked.
+**Run the analysis as a deterministic multi-agent Workflow** — invoke the Workflow
+tool with `scriptPath: .claude/workflows/gap-analysis.js`,
+`args: { "scope": "$ARGUMENTS" }`. One agent analyzes each gap dimension in its own
+context, in parallel; a final agent synthesizes the recommended order. (Invoking
+Workflow here is expected.)
+
+The workflow returns `{ scope, totalGaps, byDimension, recommendedOrder }` covering:
+
+1. Requirements found in docs but not implemented (`docs-not-impl`).
+2. Implemented features not described in docs (`impl-not-docs`).
+3. Stories implemented but not unit-tested (`impl-not-unit`).
+4. Stories implemented but not E2E-tested (`impl-not-e2e`).
+5. Stories E2E-tested but missing important edge cases (`e2e-missing-edges`).
+6. Stories that work but fail UX/design/artistic-direction review (`ux-design`).
+7. Ambiguous or contradictory requirements (`ambiguous`).
+8. Recommended next implementation order (`recommendedOrder`).
+
+Render the dimensions + the recommended order. Do not edit files unless explicitly asked.

.claude/loop.md

@@ -22,16 +22,22 @@ budget, denylist, escalation, stop conditions). Before running, fix the loop's
 4. Start or reuse the dev server.
 5. Open the relevant localhost page in Chrome or Playwright MCP.
 6. Check browser console errors and failed network requests.
-7. Run a critic round (First-Time User, UX Flow, Designer, Artistic Direction,
-   Frontend Architecture, QA / E2E, Accessibility, Performance, Security,
-   Regression) and produce a critic matrix.
-8. **Maker/checker:** the critic that verifies a fix must be a *separate* pass from
-   the one that made it — the implementer never marks its own work "done".
+7. Run the critic round as the **critic-panel Workflow**
+   (`.claude/workflows/critic-panel.js`, `args.focus` = the current task/flow):
+   critics fan out as parallel subagents and findings are adversarially verified.
+   Render the returned `confirmed` matrix.
+8. **Maker/checker:** the pass that verifies a fix must be *separate* from the one
+   that made it — the implementer never marks its own work "done".
 9. Act **only within the trust level**:
    - L1: record findings only.
-   - L2/L3: fix blockers directly related to the current task; fix important issues
-     only if low-risk and in scope; re-run the smallest relevant test; re-check
-     browser. Never fix nice-to-haves automatically; never start unrelated refactors.
+   - L2/L3: fix the confirmed blockers + directly-related important findings via the
+     **loop-iteration Workflow** (`.claude/workflows/loop-iteration.js`,
+     `args.items` = the triaged, denylist-cleared items): an implementer subagent
+     fixes each in an isolated worktree and a *separate* verifier reviews the real
+     diff and approves/rejects (a hard denylist gate also forces escalation). For
+     each **approved** item, apply its returned `diff` patch and re-run the smallest
+     relevant check before committing; escalate `rejected`/`escalate` items. Never
+     fix nice-to-haves automatically; never start unrelated refactors.
 10. **Append a run entry** to `.claude/memory/loop-run-log.md` (see format below).
 
 ## Denylist — never touch autonomously (escalate instead)

.claude/memory/log.md

@@ -76,3 +76,40 @@ change), `rotate` (archived old entries). Format: `## [YYYY-MM-DD] <op> | <summa
   with the >500-line rotation rule). Added the maker/checker no-self-approve rule
   and `Agent isolation: worktree` note to CLAUDE.md. Filed the principle in
   topics/workflow.md.
+
+## [2026-06-29] migrate | Critic rounds → deterministic multi-agent Workflows
+- Replaced "simulate critics" (one agent role-playing the panel) with real
+  orchestration: added `.claude/workflows/critic-panel.js` (parallel critics →
+  adversarial verify → matrix) and `.claude/workflows/scan-docs.js` (per-story
+  parallel evidence → separate status verifier). Rewired `/critic-round`,
+  `/multi-agent-dev`, `/multi-agent-e2e`, `/qa-pass`, `/scan-project-docs` to invoke
+  them via the Workflow tool. Named the workflow `critic-panel` (not `critic-round`)
+  to avoid colliding with the command in the skills list.
+
+## [2026-06-29] ingest | More orchestration workflows + review fixes
+- Added `gap-analysis.js` (→ `/story-gap-analysis`), `e2e-design.js` (→
+  `/multi-agent-e2e`), and `loop-iteration.js` (maker/checker for `/loop` L2/L3).
+  Wired the commands + `.claude/loop.md`; updated README, CLAUDE.md, skills-index,
+  adoption-guide (new "Multi-agent orchestration (Workflows)" section).
+- From PR #10 review: verifier agents now fail safe (null verdict ⇒ not confirmed),
+  parallel agents get unique labels (map index), schema-required fields get fallback
+  strings, and `scan-docs` statuses are capped at "E2E tested" (browser pass is the
+  caller's job). Filed the workflow-authoring gotchas in topics/workflow.md.
+
+## [2026-06-29] lint | Ran critic-panel-style Workflow on the workflow scripts
+- Dogfooded a real multi-agent review (18 agents) over `.claude/workflows/*`: 1
+  blocker + 10 important confirmed, 0 refuted. Fixes applied:
+  - scan-docs: guard the first-stage `evidence` result (blocker — unguarded deref
+    crashed the pipeline); fail CLOSED on a missing verdict (cap the maker's
+    self-proposed status) instead of accepting it.
+  - critic-panel: `.filter(Boolean)` the verified array; MERGE duplicate findings
+    (keep corroborating critics) instead of dropping; optional `args.uiInScope`
+    (skip the 5 UI critics for non-UI changes) and `args.priorEvidence` (verify
+    against already-gathered evidence, not a re-run).
+  - loop-iteration: implementer returns the REAL `git diff`; verifier reviews the
+    actual diff (not a self-report) and the caller applies the returned patch; added
+    a hard programmatic DENYLIST gate on changedFiles (defense-in-depth).
+  - e2e-design: dedup key includes category; title coalesced before `.trim()`.
+- Lesson: a maker/checker that hands the checker only the maker's self-report is
+  weak — give the checker the real artifact (diff). Exact-title dedup also let one
+  bug appear as two findings; merge, don't drop.

.claude/memory/topics/workflow.md

@@ -19,6 +19,27 @@
   routing); the grouped "when to use" catalog is `.claude/skills-index.md`. A
   catalog file must NOT live in `.claude/commands/` — anything there auto-registers
   as its own `/command`.
+- **Fan-out commands run as deterministic multi-agent Workflows** under
+  `.claude/workflows/`, not one agent simulating critics: `critic-panel` (critics →
+  adversarial verify → matrix), `scan-docs` (per-story evidence → status verifier),
+  `gap-analysis` (per-dimension gaps → synth order), `e2e-design` (per-category
+  cases → dedup), `loop-iteration` (worktree implementer → separate verifier).
+  Commands invoke them via the Workflow tool (the sanctioned opt-in). Name a workflow
+  distinctly from any command (e.g. `critic-panel` vs the `/critic-round` command) to
+  avoid a duplicate skills-list entry. Don't force non-fan-out commands
+  (`/fix-localhost`, `/write-goal`, `/dream`, `/memory-audit`) into workflows.
+- Workflow scripts use a DSL (`agent()/parallel()/pipeline()/phase()`, top-level
+  `await`/`return`); validate syntax by wrapping the body in `async function(){…}`
+  before `node --check` (bare `node --check` reports a false "illegal return").
+  Make verifier agents **fail safe** (a null/failed verdict must NOT confirm), give
+  parallel agents **unique labels** that **always include the map index** (so
+  duplicate caller-supplied ids can't collide — `${id || 'x'}-${i}`, not `${id||i}`),
+  and provide **fallback strings** for schema-required fields. Also guard the
+  *first* pipeline stage's result before deref (`const ev = stage1 || {}`), fail
+  **closed** (don't accept a maker's self-proposed value when the checker is
+  missing), and give a maker/checker checker the **real artifact** (the diff), not
+  the maker's self-report. The DSL auto-caps concurrency (~min(16, cores-2)), so a
+  large fan-out won't spawn unbounded agents — no manual limit needed.
 - A command's `description` also lets Claude **auto-invoke** it. Add
   `disable-model-invocation: true` to heavy/code-changing commands that should be
   manual-only.