@worca/app 1.0.0 → 1.1.1

package/README.md

@@ -12,9 +12,10 @@ quality gates, pausing to ask *you* the questions that matter, and keeping
 every run isolated in its own git worktree and branch.
 
 It ships as a **web UI**, a **CLI**, and an installable **`/worca` skill** for
-Claude Code — all running the same engine.
+Claude Code — all running the same engine. See the
+**[architecture in one picture](docs/ARCHITECTURE.md)**.
 
-![Running pipeline with live flow graph and streaming log](docs/screenshots/running.png)
+[![The Worca stack — clients, the engine, the headless Claude Code harness, and model endpoints](docs/screenshots/architecture.png)](docs/ARCHITECTURE.md)
 
 ## How a run works
 
@@ -62,6 +63,8 @@ and durations, the clarify Q&A, agent transcripts, and logs:
 - **Mock mode** — the entire pipeline runs offline with a deterministic mock
   (no `claude`, no tokens) for demos, development, and CI.
 
+![Running pipeline with live flow graph and streaming log](docs/screenshots/running.png)
+
 ### Agents
 
 - **11 data-driven agents** — planner, plan refiner, plan reviewer,
@@ -69,7 +72,8 @@ and durations, the clarify Q&A, agent transcripts, and logs:
   vertical-slice tasks, one implementer each), manual-tests checklist, manual
   web-UI testing (drives a browser via Playwright), workspace scanner, and
   workspace reviewer. Each agent is a markdown prompt plus a metadata sidecar
-  — new agents drop in without engine changes.
+  declaring its typed input/output ports — new agents drop in without engine
+  changes.
 - **AI-assisted agent creation** — describe a new agent in the UI and Worca
   generates both its system prompt and metadata (or paste your own prompt and
   let it infer just the wiring); edit, regenerate, and save.
@@ -79,11 +83,13 @@ and durations, the clarify Q&A, agent transcripts, and logs:
 
 ### Workflow Composer
 
-- **Compose your own pipeline** — drag agents onto a canvas to build
-  sequential steps, parallel groups, and feedback loops (an agent that emits
-  a verdict can loop back to an earlier step until it passes or hits its
-  cycle cap). Saved workflows appear in the New Pipeline picker; **Reset to
-  default** redraws the standard Plan → Refine → Implement → Review.
+- **Compose your own pipeline** — drag agents onto a canvas and wire their typed
+  ports: each card declares what it consumes and produces, a wire only connects
+  compatible ports, and a wire that closes a cycle becomes a loop with its own
+  cycle cap (a reviewer keeps sending work back until it passes or the budget
+  runs out). Flow cards — **Task** (the run's request), **End** (the result),
+  **AND**, **OR**, **Combine** — express joins, choices and merges without any
+  code. Saved pipelines appear in the New Pipeline picker.
 
 ![Workflow Composer — drag agents into steps, groups, and feedback loops](docs/screenshots/composer.png)
 
@@ -158,7 +164,13 @@ Requirements:
 
 - **Node.js >= 22.13.0** (the built-in `node:sqlite` store)
 - The **[Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI**
-  (`claude`) on your `PATH` — for real runs; mock mode needs nothing
+  (`claude`) on your `PATH` — for real runs; mock mode needs nothing.
+  On **native Windows** both the [native installer](https://docs.anthropic.com/en/docs/claude-code/setup)
+  (`claude.exe`) and `npm install -g @anthropic-ai/claude-code` work: npm puts a
+  `claude.cmd` shim on `PATH` that Node cannot spawn, so Worca runs the package's
+  native `claude.exe` next to it instead. If that binary is missing (the package's
+  `postinstall` didn't run) or the layout isn't npm's, Worca says so rather than
+  a bare `ENOENT`; `WORCA_CLAUDE_BIN` can always point at a `claude.exe` directly.
 
 ## Quick start
 
@@ -209,6 +221,7 @@ The skill starts the same deterministic orchestrator.
 
 ## Documentation
 
+- [Architecture](docs/ARCHITECTURE.md) — the whole stack in one picture
 - [Guardrails](docs/guardrails.md) — policy model, enforcement, limitations
 - [Storage](docs/storage.md) — where state lives, project keys, migration
 - [Releasing](docs/RELEASING.md) — how `@worca/app` versions are published

package/agents/clarify.meta.json

@@ -1,5 +1,9 @@
 {
   "key": "clarify",
+  "metaVersion": 2,
+  "mockRole": "clarify",
+  "inputs": [{ "id": "task", "type": "md" }],
+  "outputs": [{ "id": "answers", "type": "json", "filename": "clarify.json", "artifactKind": "clarify" }],
   "domain": "coding",
   "displayName": "Clarify",
   "description": "Turns hidden decisions into questions before planning. Multiple-choice, so later steps never guess.",
@@ -7,11 +11,7 @@
   "icon": "<circle cx=\"12\" cy=\"12\" r=\"9\"/><path d=\"M9.4 9.3a2.7 2.7 0 0 1 5.2 1c0 1.8-2.6 2.1-2.6 3.6\" stroke-linecap=\"round\" fill=\"none\"/><circle cx=\"12\" cy=\"17\" r=\"0.7\" fill=\"currentColor\" stroke=\"none\"/>",
   "agentFile": "worca-cc-clarify.md",
   "runnerType": "clarifier",
-  "loopSource": false,
   "fanOut": true,
-  "produces": ["clarify"],
-  "consumes": ["userPrompt"],
-  "connectsTo": ["planner"],
   "asksQuestions": true,
   "questionsLocked": true,
   "questionsDefault": true,

package/agents/decomposer.meta.json

@@ -1,5 +1,10 @@
 {
   "key": "decomposer",
+  "metaVersion": 2,
+  "mockRole": "decomposer",
+  "promptHints": "Read the approved plan and break it into tracer-bullet vertical slices grouped into ordered phases. Within a phase, tasks must be parallel-safe and edit DISJOINT files; dependencies are expressed only as phase order. Write each task as a SELF-CONTAINED markdown file so an implementer needs nothing but that file.",
+  "inputs": [{ "id": "plan", "type": "md" }],
+  "outputs": [{ "id": "tasks", "type": "json", "filename": "decomposition.json", "artifactKind": "decomposition" }],
   "domain": "coding",
   "displayName": "Decompose",
   "description": "Splits an approved plan into vertical-slice tasks. Each task gets its own implementer.",
@@ -8,12 +13,7 @@
   "icon": "<path d=\"M12 3v6M12 9l-5 5M12 9l5 5M5 14h2M17 14h2M6 18h2M16 18h2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>",
   "agentFile": "worca-cc-decomposer.md",
   "runnerType": "producer",
-  "loopSource": false,
   "fanOut": true,
-  "produces": ["decomposition"],
-  "consumes": ["plan"],
-  "optionalConsumes": [],
-  "connectsTo": ["implementer"],
   "asksQuestions": true,
   "questionsLocked": false,
   "questionsDefault": false,

package/agents/implementer.meta.json

@@ -1,5 +1,20 @@
 {
   "key": "implementer",
+  "metaVersion": 2,
+  "mockRole": "implementer",
+  "sideEffect": "code",
+  "workspaceFanOut": true,
+  "workspaceStrategy": "task",
+  "promptHints": "Work inside the project directory (your cwd). Commit nothing; just edit files and tests.",
+  "inputs": [
+    { "id": "fix", "type": "md", "required": false, "loop": true, "as": "fix-review",
+      "directive": "Address EVERY critical and major issue in the review below, then re-run the tests. Follow the plan; deviate only if something does not work at all." },
+    { "id": "task", "type": "json", "required": false, "expands": true,
+      "directive": "Implement the task below using TDD (red-green-refactor). The TASK file is a self-contained vertical slice and is AUTHORITATIVE — do exactly what it says and nothing outside its scope. The plan is reference/context only; you do NOT need to read the whole plan." },
+    { "id": "plan", "type": "md",
+      "directive": "Implement the plan using TDD (red-green-refactor). Follow it with NO deviation; deviate slightly only if a step does not work at all." }
+  ],
+  "outputs": [{ "id": "done", "type": "void" }],
   "domain": "coding",
   "displayName": "Implementation",
   "description": "Writes the code from the approved plan, strict TDD. In fix mode, addresses only the issues a review flagged.",
@@ -7,12 +22,7 @@
   "icon": "<path d=\"M9 8l-4 4 4 4M15 8l4 4-4 4\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>",
   "agentFile": "worca-cc-implementer.md",
   "runnerType": "producer",
-  "loopSource": false,
   "fanOut": true,
-  "produces": ["code"],
-  "consumes": ["plan","review"],
-  "optionalConsumes": ["review"],
-  "connectsTo": ["reviewer","manualTestsChecklist"],
   "asksQuestions": true,
   "questionsLocked": false,
   "questionsDefault": false,

package/agents/manualTestsChecklist.meta.json

@@ -1,5 +1,10 @@
 {
   "key": "manualTestsChecklist",
+  "metaVersion": 2,
+  "mockRole": "manual-tests-checklist",
+  "promptHints": "Read the implementation plan and the implemented changes ({diffInstruction}), then write a markdown checklist of concrete manual test cases a human can run against the app. Each case: a `- [ ]` line with steps and the expected result.",
+  "inputs": [{ "id": "plan", "type": "md" }],
+  "outputs": [{ "id": "checklist", "type": "md", "filename": "manual-tests-checklist.md" }],
   "domain": "coding",
   "displayName": "Manual Tests Checklist",
   "description": "Drafts a manual test checklist for the change. User-visible flows, edge cases, regressions worth clicking through.",
@@ -7,10 +12,6 @@
   "icon": "<rect x=\"6\" y=\"4\" width=\"12\" height=\"17\" rx=\"2\"/><path d=\"M9.5 4V2.8h5V4\" stroke-linejoin=\"round\"/><path d=\"M8.8 12l1.6 1.6L13.4 10\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>",
   "agentFile": "worca-cc-manual-tests-checklist.md",
   "runnerType": "producer",
-  "loopSource": false,
-  "produces": ["checklist"],
-  "consumes": ["plan","code"],
-  "connectsTo": ["manualWebUiTesting"],
   "asksQuestions": true,
   "questionsLocked": false,
   "questionsDefault": false,

package/agents/manualWebUiTesting.meta.json

@@ -1,5 +1,14 @@
 {
   "key": "manualWebUiTesting",
+  "metaVersion": 2,
+  "mockRole": "manual-web-ui-testing",
+  "promptHints": "Execute the manual test checklist against the running web UI using the Playwright tools. Severity calibration: a failing manual case is at least major.",
+  "verdict": { "filename": "webui-review-cycle{cycle}.json" },
+  "inputs": [{ "id": "checklist", "type": "md" }],
+  "outputs": [
+    { "id": "review", "type": "md", "when": "blocking", "filename": "webui-review-cycle{cycle}.md", "artifactKind": "webui" },
+    { "id": "pass", "type": "void", "when": "clean" }
+  ],
   "domain": "coding",
   "displayName": "Manual web UI testing",
   "description": "Runs the manual checklist in the live web UI via Playwright. Reports what passed, failed, or blocked.",
@@ -7,10 +16,6 @@
   "icon": "<circle cx=\"12\" cy=\"12\" r=\"9\"/><path d=\"M10 8.5l5 3.5-5 3.5V8.5Z\" fill=\"currentColor\" stroke=\"none\"/>",
   "agentFile": "worca-cc-manual-web-ui-testing.md",
   "runnerType": "verifier",
-  "loopSource": true,
-  "produces": ["review"],
-  "consumes": ["checklist","code"],
-  "connectsTo": ["implementer"],
   "asksQuestions": true,
   "questionsLocked": false,
   "questionsDefault": false,

package/agents/planReviewer.meta.json

@@ -1,5 +1,17 @@
 {
   "key": "planReviewer",
+  "metaVersion": 2,
+  "mockRole": "plan-review",
+  "promptHints": "Review the implementation PLAN against the original request and the real codebase. Do NOT rewrite the plan. Only critical/major block (the planner then revises).",
+  "wantsRequest": true,
+  "workspaceFanOut": true,
+  "workspaceStrategy": "explore",
+  "verdict": { "filename": "plan-review-cycle{cycle}.json" },
+  "inputs": [{ "id": "plan", "type": "md" }],
+  "outputs": [
+    { "id": "review", "type": "md", "when": "blocking", "filename": "{base}-plan-review.md", "store": "project" },
+    { "id": "pass", "type": "void", "when": "clean" }
+  ],
   "domain": "coding",
   "displayName": "Plan Review",
   "description": "Reviews the plan against the request and the codebase. Blocking issues bounce it back for a cold re-plan.",
@@ -7,11 +19,7 @@
   "icon": "<path d=\"M10.5 4a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13Z\"/><path d=\"M15.5 15.5L21 21\" stroke-linecap=\"round\"/><path d=\"M7.6 10.3l2 2 3.3-3.6\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>",
   "agentFile": "worca-cc-plan-reviewer.md",
   "runnerType": "verifier",
-  "loopSource": true,
   "fanOut": true,
-  "produces": ["review"],
-  "consumes": ["plan"],
-  "connectsTo": ["planner", "implementer", "decomposer"],
   "asksQuestions": true,
   "questionsLocked": false,
   "questionsDefault": false,

package/agents/planner.meta.json

@@ -1,5 +1,17 @@
 {
   "key": "planner",
+  "metaVersion": 2,
+  "mockRole": "planner-plan",
+  "promptHints": "Write a complete, build-ready implementation plan. It MUST contain concrete code snippets for the features and MUST end with a \"## Clarifications (Q&A)\" section reproducing the questions and the user answers below so the reviewer can see them.",
+  "workspaceFanOut": true,
+  "workspaceStrategy": "explore",
+  "inputs": [
+    { "id": "task", "type": "md" },
+    { "id": "answers", "type": "json", "required": false, "as": "answers" },
+    { "id": "revise", "type": "md", "required": false, "loop": true,
+      "directive": "## Revise to address the review\n\nA reviewer found issues with the previous plan. Re-plan from scratch (cold start) and address EVERY critical and major finding in the review below. Preserve the \"## Clarifications (Q&A)\" section." }
+  ],
+  "outputs": [{ "id": "plan", "type": "md", "filename": "{base}{vsuffix}.md", "store": "project" }],
   "domain": "coding",
   "displayName": "Plan",
   "description": "Explores the codebase and writes the implementation plan. Architecture, task breakdown, concrete code snippets; can ask clarifying questions first.",
@@ -7,12 +19,7 @@
   "icon": "<path d=\"M8 6h11M8 12h11M8 18h8\" stroke-linecap=\"round\"/><circle cx=\"4\" cy=\"6\" r=\"1.1\"/><circle cx=\"4\" cy=\"12\" r=\"1.1\"/><circle cx=\"4\" cy=\"18\" r=\"1.1\"/>",
   "agentFile": "worca-cc-planner.md",
   "runnerType": "producer",
-  "loopSource": false,
   "fanOut": true,
-  "produces": ["plan"],
-  "consumes": ["userPrompt", "clarify", "review"],
-  "optionalConsumes": ["clarify", "review"],
-  "connectsTo": ["refiner", "implementer", "planReviewer", "decomposer"],
   "asksQuestions": true,
   "questionsLocked": false,
   "questionsDefault": false,

package/agents/refiner.meta.json

@@ -1,5 +1,20 @@
 {
   "key": "refiner",
+  "metaVersion": 2,
+  "mockRole": "refiner",
+  "promptHints": "Read the current plan, critically review it INCLUDING its code snippets, then write an improved version and a machine-readable review.\n\nMark a finding critical/major only if it must be fixed before implementation.",
+  "wantsRequest": true,
+  "workspaceFanOut": true,
+  "workspaceStrategy": "explore",
+  "verdict": { "filename": "refine-review-cycle{cycle}.json" },
+  "inputs": [
+    { "id": "plan", "type": "md" },
+    { "id": "revise", "type": "md", "required": false, "loop": true }
+  ],
+  "outputs": [
+    { "id": "plan", "type": "md", "when": "clean", "filename": "{base}{vsuffix}.md", "store": "project" },
+    { "id": "revise", "type": "md", "when": "blocking", "filename": "{base}{vsuffix}.md", "store": "project", "artifactKind": "plan" }
+  ],
   "domain": "coding",
   "displayName": "Refine Plan",
   "description": "Rewrites the latest plan into a tighter version. Fixes structure, correctness, and code snippets until no blocking issues remain.",
@@ -7,11 +22,7 @@
   "icon": "<path d=\"M12 3v3M12 18v3M4.5 7.5l2 1M17.5 15.5l2 1M4.5 16.5l2-1M17.5 8.5l2-1\" stroke-linecap=\"round\"/><path d=\"M12 8.2l1.2 2.6L16 12l-2.8 1.2L12 15.8l-1.2-2.6L8 12l2.8-1.2L12 8.2Z\" stroke-linejoin=\"round\"/>",
   "agentFile": "worca-cc-plan-refiner.md",
   "runnerType": "producer",
-  "loopSource": false,
   "fanOut": true,
-  "produces": ["plan","review"],
-  "consumes": ["plan"],
-  "connectsTo": ["implementer","refiner","decomposer"],
   "asksQuestions": true,
   "questionsLocked": false,
   "questionsDefault": false,

package/agents/reviewer.meta.json

@@ -1,5 +1,19 @@
 {
   "key": "reviewer",
+  "metaVersion": 2,
+  "mockRole": "reviewer",
+  "promptHints": "Review the git diff of what was implemented against the plan.",
+  "wantsRequest": true,
+  "workspaceStrategy": "review",
+  "verdict": { "filename": "impl-review-cycle{cycle}.json" },
+  "inputs": [
+    { "id": "plan", "type": "md" },
+    { "id": "done", "type": "void", "required": false, "as": "worktree" }
+  ],
+  "outputs": [
+    { "id": "review", "type": "md", "when": "blocking", "filename": "{base}-impl-review.md", "store": "project" },
+    { "id": "pass", "type": "void", "when": "clean" }
+  ],
   "domain": "coding",
   "displayName": "Review Implementation",
   "description": "Reviews the implementation diff against the plan. Honest verdict; blocking findings loop back to the implementer.",
@@ -7,11 +21,7 @@
   "icon": "<path d=\"M12 3l7 3v5c0 4.4-3 7.6-7 9-4-1.4-7-4.6-7-9V6l7-3Z\" stroke-linejoin=\"round\"/><path d=\"M9 12l2 2 4-4\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>",
   "agentFile": "worca-cc-code-reviewer.md",
   "runnerType": "verifier",
-  "loopSource": true,
   "fanOut": true,
-  "produces": ["review"],
-  "consumes": ["plan","code"],
-  "connectsTo": ["implementer","manualTestsChecklist"],
   "asksQuestions": true,
   "questionsLocked": false,
   "questionsDefault": false,

package/agents/worca-cc-clarify.md

@@ -7,6 +7,13 @@ model: inherit
 
 You are the **Clarify** agent in a deterministic multi-agent pipeline (Clarify -> Plan -> Refine -> Implement -> Review). You are spawned headlessly by an orchestrator script and run BEFORE the Planner. Your sole job is to surface the few genuine open decisions, so the Planner can plan without guessing. You NEVER write a plan.
 
+## Ports
+
+The engine binds every port to an absolute path in the task prompt — never hardcode filenames.
+
+- **in `task`** (md) — the user's task/prompt (plus any attached markdown / extra files).
+- **out `answers`** (json) — your questions, in the shape contracted below. The engine folds the user's answers back into this same file.
+
 ## Cardinal rule: NEVER ASSUME, NEVER PAD
 
 Surface the decisions that **materially** change the plan — core requirements, scope boundaries, externally-visible behavior, data shapes, or library/architecture choices — that you genuinely cannot resolve from the task text or the codebase. **Actively hunt for the things a downstream agent (planner/implementer) would otherwise silently assume** and turn each into a question. At the same time, do NOT ask stupid or unnecessary questions: for **low-impact** details (naming, minor file placement, obvious conventions, anything readable from the codebase), do NOT ask — the Planner will pick a sensible default. Ask only what you genuinely cannot decide.

package/agents/worca-cc-code-reviewer.md

@@ -7,12 +7,17 @@ model: inherit
 
 You are the **Code Reviewer** agent in a deterministic Plan -> Refine -> Implement -> Review pipeline. You are spawned headlessly, once per review cycle. After your review, the orchestrator runs the Implementer in FIX mode against your findings, then runs you again — looping until you report NO critical and NO major issues (or a cycle cap with a user gate). Your honesty about severities controls the loop: do not downgrade real defects to end it, and do not invent blocking issues to prolong it.
 
-## Inputs (from the task prompt)
-- The absolute path of the PLAN that was implemented.
-- The absolute path to write the review markdown. The orchestrator places it in the machine-wide external store, keyed by repo identity and outside the working tree (e.g. `<worcaHome>/store/<projectKey>/reviews/<DD-MM-YY-name>-impl-review.md`, default `~/.worca-cc/store/<projectKey>/reviews/...`). Always write to the exact absolute path you are given.
-- The absolute path to write `review-cycleN.json`.
-- The cycle number.
-- Your cwd is the project repo, so you can run git.
+## Ports
+
+The engine binds every port to an absolute path in the task prompt — never hardcode filenames.
+
+- **in `plan`** (md) — the plan that was implemented.
+- **in `done`** (void, optional) — the implementer's staged worktree. Review THAT tree's diff.
+- **out `review`** (md, on a blocking verdict) — your review markdown.
+- **out `pass`** (void, on a clean verdict) — the no-blocking-issues signal; it carries no file.
+- **verdict** (json) — the review JSON the orchestrator gates on; its shape is contracted below.
+
+Your cwd is the project repo, so you can run git. The cycle number is in the task prompt.
 
 ## What to do
 

package/agents/worca-cc-decomposer.md

@@ -12,6 +12,13 @@ path is in the prompt). Break it into **tracer-bullet vertical slices** so that
 parallel implementers can each pick up one self-contained task file without reading
 the whole plan.
 
+## Ports
+
+The engine binds every port to an absolute path in the task prompt — never hardcode filenames.
+
+- **in `plan`** (md) — the approved implementation plan to split.
+- **out `tasks`** (json) — the decomposition manifest, in the shape contracted below. The per-task markdown files go in the tasks directory the prompt names.
+
 ## Draft vertical slices
 
 Break the plan into thin vertical slices. Each slice is a tracer bullet that cuts

package/agents/worca-cc-implementer.md

@@ -7,6 +7,15 @@ model: inherit
 
 You are the **Implementer** agent in a deterministic Plan -> Refine -> Implement -> Review pipeline. You are spawned headlessly. You operate in ONE of two modes, stated in the task prompt: `implement` or `fix`. You write real code into the target project working directory (your cwd is the project). The Code Reviewer will inspect your changes via `git diff` against the orchestrator's checkpoint commit, so your changes must be real, committed-quality work. You do not need to stage or commit — the orchestrator records intent-to-add for any new files after you finish so they show up in the reviewer's diff.
 
+## Ports
+
+The engine binds every port to an absolute path in the task prompt — never hardcode filenames.
+
+- **in `fix`** (md, optional, loop) — a code review to address. When it is bound, you are in FIX mode.
+- **in `task`** (json, optional) — one decomposed vertical slice. When it is bound, that task file is authoritative and the plan is reference only.
+- **in `plan`** (md) — the approved implementation plan. Always bound.
+- **out `done`** (void) — the signal that the working tree now carries your change; it carries no file.
+
 ## Cardinal rule: FOLLOW THE PLAN
 
 The latest plan (its absolute path is in the prompt) is authoritative. Implement it faithfully, step by step, with NO deviation in approach, file layout, naming, or scope. Do not add features the plan does not call for. Do not refactor unrelated code. Do not "improve" the design on your own initiative.

package/agents/worca-cc-manual-tests-checklist.md

@@ -7,11 +7,14 @@ model: inherit
 
 You are the **Manual Tests Checklist** agent in a deterministic multi-agent pipeline (Plan -> Refine -> Implement -> Review, with optional manual-testing steps). You are spawned headlessly. Your single deliverable is a **markdown checklist of manual test cases** written to the absolute path given in the task prompt. You do not run the app, write code, or emit a review verdict — you author the checklist that a human (or the Manual web UI testing agent) will execute.
 
-## Inputs (from the task prompt)
-- The user's original request / task description.
-- The absolute path of the approved PLAN markdown (the latest `-vN`).
-- Access to the implementation via git: your cwd is the project repo. If a checkpoint ref is named, `git diff <ref>` shows the implemented change (new files are intent-to-added, so they appear); otherwise use `git diff` plus `git diff HEAD`, and always cross-check with `git status` and `git diff --stat` (a plain `git diff` can look empty when the change is entirely new files).
-- The absolute output path for the checklist markdown (e.g. a `MOCK_OUT:` line or an explicit "write the checklist to <path>" instruction). Use that path verbatim.
+## Ports
+
+The engine binds every port to an absolute path in the task prompt — never hardcode filenames.
+
+- **in `plan`** (md) — the approved implementation plan.
+- **out `checklist`** (md) — the manual test checklist you author.
+
+The user's original request comes with the task prompt. Access to the implementation is via git: your cwd is the project repo. If a checkpoint ref is named, `git diff <ref>` shows the implemented change (new files are intent-to-added, so they appear); otherwise use `git diff` plus `git diff HEAD`, and always cross-check with `git status` and `git diff --stat` (a plain `git diff` can look empty when the change is entirely new files).
 
 ## What to do
 1. Read the plan in full to learn the intended behavior, scope, and acceptance criteria.

package/agents/worca-cc-manual-web-ui-testing.md

@@ -7,12 +7,16 @@ model: inherit
 
 You are the **Manual web UI testing** agent in a deterministic Plan -> Refine -> Implement -> Review pipeline (with manual-testing steps). You are spawned headlessly, once per testing cycle. You **execute the manual test checklist against the live, running web UI** using the Playwright MCP browser tools, and you write a verdict JSON. The orchestrator gates on your verdict: if you report critical/major issues, it runs the Implementer in FIX mode and re-runs you — looping until you report none (or a cycle cap with a user gate). Your honesty about severities controls the loop: do not downgrade real defects to end it, and do not invent blocking issues to prolong it.
 
-## Inputs (from the task prompt)
-- The absolute path of the manual test **checklist markdown** to execute (authored by the Manual Tests Checklist agent). Each `- [ ]` item is a case with steps + an Expected result.
-- The absolute path of the PLAN that was implemented (for context on intended behavior).
-- The absolute path to write `review-cycleN.json`.
-- The cycle number.
-- Optionally a screenshots directory under the pipeline dir to save evidence.
+## Ports
+
+The engine binds every port to an absolute path in the task prompt — never hardcode filenames.
+
+- **in `checklist`** (md) — the manual test checklist to execute (authored by the Manual Tests Checklist agent). Each `- [ ]` item is a case with steps + an Expected result.
+- **out `review`** (md, on a blocking verdict) — your findings written up as markdown.
+- **out `pass`** (void, on a clean verdict) — the no-blocking-issues signal; it carries no file.
+- **verdict** (json) — the review JSON the orchestrator gates on; its shape is contracted below.
+
+The cycle number comes with the task prompt, as does an optional screenshots directory under the pipeline dir for evidence.
 
 ## Getting the app running (required)
 The UI must be reachable before you can test it.

package/agents/worca-cc-plan-refiner.md

@@ -7,12 +7,17 @@ model: inherit
 
 You are the **Plan Refiner** agent in a deterministic Plan -> Refine -> Implement -> Review pipeline. You are spawned headlessly, once per refine cycle. The orchestrator loops you: it keeps running you (cycle 1, 2, 3 …) until your review reports NO critical and NO major issues, or a cycle cap with a user gate is reached. Your honesty about severities is what makes the loop terminate correctly — never downgrade real problems to make the loop end, and never inflate trivia to keep it going.
 
-## Inputs (from the task prompt)
-- The absolute path of the INPUT plan to review (the latest version so far).
-- The absolute path to write the REFINED plan (`-vN`, e.g. `<base>-v2.md` on cycle 1, `-v3.md` on cycle 2, …). Use the exact path given.
-- The absolute path to write `review-cycleN.json` for this cycle.
-- The cycle number.
-- The original task/prompt context and the plan's own `## Clarifications (Q&A)` section (preserve and respect the user's answers).
+## Ports
+
+The engine binds every port to an absolute path in the task prompt — never hardcode filenames.
+
+- **in `plan`** (md) — the INPUT plan to review (the latest version so far).
+- **in `revise`** (md, optional, loop) — your own previous output coming back for another cycle.
+- **out `plan`** (md, on a clean verdict) — the refined plan, when nothing blocks any more.
+- **out `revise`** (md, on a blocking verdict) — the refined plan when issues remain; it re-enters your `revise` input for the next cycle. Both arms write the SAME plan file.
+- **verdict** (json) — the review JSON the orchestrator gates on; its shape is contracted below.
+
+The cycle number, the original task/prompt context, and the plan's own `## Clarifications (Q&A)` section (preserve and respect the user's answers) come with the task prompt.
 
 ## Fan-out (parallel sub-agents) — USE IT when enabled
 

package/agents/worca-cc-plan-reviewer.md

@@ -9,13 +9,16 @@ You are the **Plan Reviewer** agent in a deterministic multi-agent pipeline. You
 
 Contrast with the Plan Refiner: the refiner reviews AND rewrites the plan itself. You only review and report; the Planner does the rewriting. Keep that separation — never edit the plan file.
 
-## Inputs (from the task prompt)
-- The absolute path of the PLAN markdown to review.
-- The original user request (in the task header) and any attached files.
-- The absolute path to write the review markdown.
-- The absolute path to write `plan-review-cycleN.json`.
-- The cycle number.
-- Your cwd is the project repo, so you can inspect the real codebase.
+## Ports
+
+The engine binds every port to an absolute path in the task prompt — never hardcode filenames.
+
+- **in `plan`** (md) — the plan markdown to review.
+- **out `review`** (md, on a blocking verdict) — your review markdown.
+- **out `pass`** (void, on a clean verdict) — the no-blocking-issues signal; it carries no file.
+- **verdict** (json) — the review JSON the orchestrator gates on; its shape is contracted below.
+
+The original user request (in the task header), any attached files, and the cycle number come with the task prompt. Your cwd is the project repo, so you can inspect the real codebase.
 
 ## What to do
 

package/agents/worca-cc-planner.md

@@ -7,6 +7,15 @@ model: inherit
 
 You are the **Planner** agent in a deterministic multi-agent pipeline (Plan -> Refine -> Implement -> Review). You are spawned headlessly by an orchestrator script. You write implementation plans (PLAN), and on a plan-review rewind you revise from the review (REVISE). You never ask the user questions — a separate Clarify agent runs before you and its answers are provided in your task prompt. Read the task prompt carefully and obey the mode markers.
 
+## Ports
+
+The engine binds every port to an absolute path in the task prompt — never hardcode filenames.
+
+- **in `task`** (md) — the user's task/prompt (plus any attachments).
+- **in `answers`** (json, optional) — the Clarify agent's questions and the user's answers. Honor them.
+- **in `revise`** (md, optional, loop) — a plan review that bounced the plan back. When it is bound, you are in REVISE mode (see below).
+- **out `plan`** (md) — the implementation plan you write.
+
 ## Fan-out (parallel sub-agents) — USE IT when enabled
 
 The orchestrator decides per run whether you may fan out. When it is enabled, your task prompt carries a `## Fan-out ENABLED` block AND the **Task/Agent tool is in your tool list**. In that case, do NOT explore the codebase serially when the work spans multiple areas. Instead:

package/agents/worca-cc-workspace-reviewer.md

@@ -7,10 +7,17 @@ model: inherit
 
 You are the **Workspace Reviewer** agent in a deterministic Plan -> Refine -> Implement -> Review pipeline running over a WORKSPACE (a set of 2+ member projects). You replace the single-project Code Reviewer for workspace runs. You are spawned headlessly, once per review cycle. After your review, the orchestrator runs the Implementer in FIX mode against your findings, then runs you again — looping until you report NO critical and NO major issues (or a cycle cap with a user gate). Your honesty about severities controls the loop: do not downgrade real defects to end it, and do not invent blocking issues to prolong it. As fixes land across cycles, your blocking count should genuinely fall.
 
-## Inputs (from the task prompt)
-- The `## Workspace Context` block (the frozen, point-in-time interconnection description) and the `## Workspace projects` block listing each member's worktree directory (a sub-agent's cwd) and its checkpoint ref (the diff base).
-- The absolute path of the PLAN that was implemented.
-- The absolute path to write the synthesized review markdown, the absolute path to write `review-cycleN.json`, and the cycle number.
+## Ports
+
+The engine binds every port to an absolute path in the task prompt — never hardcode filenames.
+
+- **in `plan`** (md) — the plan that was implemented.
+- **in `done`** (void, optional) — the implementer's staged worktrees. Review THOSE trees' diffs.
+- **out `review`** (md, on a blocking verdict) — your ONE synthesized review markdown.
+- **out `pass`** (void, on a clean verdict) — the no-blocking-issues signal; it carries no file.
+- **verdict** (json) — the single synthesized review JSON the orchestrator gates on; its shape is contracted below.
+
+The task prompt also carries the `## Workspace Context` block (the frozen, point-in-time interconnection description), the `## Workspace projects` block listing each member's worktree directory (a sub-agent's cwd) and its checkpoint ref (the diff base), and the cycle number.
 
 ## What to do (review-fanout, cap 8)
 

package/agents/worca-cc-workspace-scanner.md

@@ -7,10 +7,14 @@ model: inherit
 
 You are the **Workspace Scanner** agent. You run OUTSIDE the Plan -> Refine -> Implement -> Review pipeline: the wizard's scan engine spawns you once, before a workspace is saved, to discover how its member projects interconnect and to write a single, human-editable interconnection description. You are strictly **read-only** — you investigate and report; you NEVER edit, commit, or branch in any member repo.
 
-## Inputs (from the task prompt)
-- The member projects: each project's name, `projectKey`, and the directory to investigate (a throwaway worktree when graphify built a graph there, else the project root).
-- For each project, whether a `graphify-out/` knowledge graph is available (use it when present; otherwise fall back to `Read`/`Grep`/`Glob`).
-- The absolute path to write the interconnection description markdown.
+## Ports
+
+The engine binds every port to an absolute path in the task prompt — never hardcode filenames.
+
+- **in `task`** (md) — the scan request.
+- **out `workspace`** (md) — the interconnection description you write.
+
+The task prompt also names the member projects — each project's name, `projectKey`, and the directory to investigate (a throwaway worktree when graphify built a graph there, else the project root) — and, per project, whether a `graphify-out/` knowledge graph is available (use it when present; otherwise fall back to `Read`/`Grep`/`Glob`).
 
 ## What to do
 

package/agents/workspaceReviewer.meta.json

@@ -1,5 +1,20 @@
 {
   "key": "workspaceReviewer",
+  "metaVersion": 2,
+  "mockRole": "workspace-reviewer",
+  "workspaceVariantOf": "reviewer",
+  "promptHints": "Review what was implemented across the member projects against the plan.\n\nThe issue list is the UNION of every per-project critical/major issue (never collapse one), sorted by projectKey then severity, each location prefixed \"<projectKey>: \".",
+  "workspaceFanOut": true,
+  "workspaceStrategy": "review",
+  "verdict": { "filename": "ws-review-cycle{cycle}.json" },
+  "inputs": [
+    { "id": "plan", "type": "md" },
+    { "id": "done", "type": "void", "required": false, "as": "worktree" }
+  ],
+  "outputs": [
+    { "id": "review", "type": "md", "when": "blocking", "filename": "{base}-ws-review.md", "store": "project" },
+    { "id": "pass", "type": "void", "when": "clean" }
+  ],
   "domain": "shared",
   "displayName": "Workspace Review",
   "description": "Fans out one review per changed project in the workspace. Synthesizes a single cross-project verdict.",
@@ -7,11 +22,7 @@
   "icon": "<path d=\"M12 3l7 3v5c0 4.4-3 7.6-7 9-4-1.4-7-4.6-7-9V6l7-3Z\" stroke-linejoin=\"round\"/><path d=\"M8 11l2 2 4-4\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>",
   "agentFile": "worca-cc-workspace-reviewer.md",
   "runnerType": "verifier",
-  "loopSource": true,
   "fanOut": true,
-  "produces": ["review"],
-  "consumes": ["plan", "code"],
-  "connectsTo": ["implementer"],
   "asksQuestions": true,
   "questionsLocked": false,
   "questionsDefault": false,