@worca/app 0.0.1

package/README.md

@@ -0,0 +1,403 @@
+# Worca CC
+
+A **deterministic multi-agent pipeline** that drives Claude Code (headless) through
+**Plan -> Refine -> Implement -> Review** for a software task. It ships three ways to
+run the same pipeline: a **CLI**, an installable **`/worca` skill**, and a **web
+UI**.
+
+Plain Node.js ESM (`.mjs`), **Node `>=22.13.0`** — required by the built-in
+`node:sqlite` store (flag-free from Node v22.13 LTS / v23.4+). Minimal dependencies:
+`express` + `ws` only. The frontend is vanilla HTML/CSS/JS — no framework, no build step.
+
+> The full, binding contract for every module, event, and on-disk file lives in
+> [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). Read it before changing any signature.
+
+---
+
+## What it is
+
+You give the orchestrator a **project folder** and a **prompt** (or a markdown brief).
+A deterministic state machine then runs the agents of the selected workflow in sequence, looping until the work
+clears quality gates:
+
+1. **Planner** writes an initial plan (with code snippets) and, instead of *assuming*
+   anything, asks you conceptual questions — each with **2–4 options plus a free-text
+   field**. The Q&A is appended to the plan so reviewers see it.
+2. **Plan Refiner** reviews the plan (including its code snippets), writes a refined
+   `-v2`, `-v3`, ... and re-runs until only minor/suggestion issues remain (or you
+   approve continuing past the cycle cap).
+3. **Implementer** follows the latest plan with no deviation, using TDD
+   (red-green-refactor).
+4. **Code Reviewer** reviews the git diff, writes a review, and hands back to the
+   implementer to fix — looping Implement -> Review until only minor/suggestion issues
+   remain (or you approve continuing past the cap).
+
+Run state, history, and configuration are saved in a single **SQLite database**
+(`~/.worca-cc/worca-cc.db`, via the built-in `node:sqlite`), while the agents' **markdown**
+outputs (plans, reviews) and any attachments live alongside it in a **machine-wide
+external store** (default `~/.worca-cc/store/<projectKey>/`). Both are keyed by repo
+identity and kept **outside your project's working tree**, so nothing is ever committed to
+your repo. See [Artifact layout](#artifact-layout) for details.
+
+### Preflight tooling
+
+Before planning, the orchestrator probes for optional graph tools and, if present,
+tells the agents to use them:
+
+- [`graphify`](https://github.com/safishamsi/graphify)
+- [`code-review-graph`](https://github.com/tirth8205/code-review-graph)
+
+If **both** are installed, it **always uses graphify**. All probes fail safe — a
+missing tool never breaks a run.
+
+---
+
+## Install
+
+```bash
+npm install
+```
+
+Requires **Node `>=22.13.0`** (for the built-in `node:sqlite` store — run `nvm use` to
+pick up the bundled `.nvmrc`) and the `claude` CLI on your `PATH` for real (non-mock) runs.
+
+---
+
+## Quick start
+
+### CLI
+
+Run a pipeline against a project folder:
+
+```bash
+npm run cli -- --project /path/to/your/project --prompt "Add a /search endpoint"
+```
+
+Or use a markdown brief as the prompt:
+
+```bash
+npm run cli -- --project /path/to/your/project --file ./brief.md --title "Search feature"
+```
+
+Useful flags: `--model <m>`,
+`--permission-mode <m>`, `--yes`/`--non-interactive` (auto-answer clarify with the
+first option and gates with "continue"). See `docs/ARCHITECTURE.md` §4.1 for the full
+list.
+
+### Web UI
+
+```bash
+npm start
+```
+
+Then open the printed URL (default `http://localhost:4317`). The UI lets you:
+
+- start a run from a **prompt or markdown document**, pointed at any **project folder**,
+  with optional extra files;
+- watch a **steps tracker** (preflight / plan / refine #N / implement / review #N /
+  done);
+- answer **clarify questions** (2–4 options + free text) and **loop gates** ("Don't have
+  another cycle and continue" / "I approve another cycle", with the open critical/major
+  issues shown);
+- follow a **live streaming log**;
+- **Pause** or **Stop** a run;
+- browse **history** of past pipelines and read their saved markdown.
+
+There's also an **"Install agents into this folder"** button that copies the agents +
+skill into a target project so you can use `/worca` there.
+
+### Pause & resume
+
+A running pipeline can be **paused** and continued later — even from a fresh process:
+
+- **Web UI** — every run card has a **Pause** button next to Stop; a paused pipeline
+  shows an amber **Paused** badge in history, and its history card gets a **Resume**
+  button.
+- **CLI** — the first `Ctrl+C` pauses gracefully (a second stops, a third hard-exits).
+  Continue later with:
+
+```bash
+npm run cli -- resume <pipelineId>
+# or, with the bin on your PATH: worca resume <pipelineId>
+```
+
+Pause is graceful: in-flight Claude steps are terminated, the per-pipeline **worktree
+is kept** (uncommitted agent work survives), and a **resume point** is persisted to the
+database — so resume **survives server restarts** (it rehydrates entirely from the DB).
+On resume, interrupted steps **re-attach their Claude session** via
+`claude --resume <session_id>`; if the session is gone, the step re-runs fresh and the
+fallback is noted in the run's audit log.
+
+### `/worca` skill (inside your own project)
+
+Copy the agents and the skill into your project's `.claude/`:
+
+```bash
+npm run install:agents -- /path/to/your/project
+# or: node scripts/install.mjs /path/to/your/project [--force]
+```
+
+Then open Claude Code in that project and run:
+
+```
+/worca Add a /search endpoint with pagination
+```
+
+The skill starts the same deterministic orchestrator script.
+
+### Mock demo (offline, no tokens)
+
+The whole pipeline can run **fully offline** without spawning `claude` — it produces
+real artifact files using a deterministic mock:
+
+```bash
+npm run smoke
+```
+
+This is equivalent to:
+
+```bash
+WORCA_MOCK=1 node src/cli/worca-cc.mjs --project sandbox --prompt "demo task" --mock --yes
+```
+
+Set `WORCA_MOCK=1` (or pass `--mock`) on any run to use the mock path.
+
+---
+
+## The agents
+
+| Agent | File | Role |
+| --- | --- | --- |
+| Planner | `agents/worca-cc-planner.md` | Initial plan with code snippets; asks conceptual questions (2–4 options + free text) instead of assuming; appends Q&A to the plan. |
+| Plan Refiner | `agents/worca-cc-plan-refiner.md` | Reviews + refines the plan (and its code snippets); writes `-vN`; emits a severity-tagged review per cycle. |
+| Plan Review | `agents/worca-cc-plan-reviewer.md` | Reviews the plan (without rewriting it); writes review markdown + JSON; on blocking issues bounces back to the planner for a cold re-plan. |
+| Implementer | `agents/worca-cc-implementer.md` | Follows the latest plan with no deviation; TDD red-green-refactor; also runs in "fix" mode against a review. |
+| Code Reviewer | `agents/worca-cc-code-reviewer.md` | Reviews the git diff; writes review markdown + JSON; hands back to the implementer to fix. |
+
+Worca CC now ships **7 runnable agents** and the agent system is **data-driven**:
+each agent is a prompt (`agents/worca-cc-<role>.md`) plus a metadata sidecar
+(`agents/<key>.meta.json`), so new agents drop in without engine edits. Beyond
+the five above, it adds **Manual Tests Checklist** (drafts manual test cases) and
+**Manual web UI testing** (runs them against the live web UI via Playwright and
+emits a pass/fail verdict). To add your own, see
+[`docs/ADDING-AGENTS.md`](docs/ADDING-AGENTS.md).
+
+---
+
+## The phases and loops
+
+- **Clarify** — planner asks one round of conceptual questions (up to four) before
+  planning; answers are persisted and appended to the plan.
+- **Refine loop** — Refiner runs repeatedly. It stops when no `critical`/`major` issues
+  remain. Past the loop's **max cycles** (default 3) it asks you to **continue** or approve
+  **another** cycle, escalating indefinitely.
+- **Review loop** — Reviewer -> Implementer(fix) -> Reviewer ... stops when no
+  `critical`/`major` issues remain. Past the loop's **max cycles** (default 3) it asks the
+  same continue/another gate.
+
+Each feedback loop's max-cycle count is set per loop in the New Pipeline window's
+**Pipeline configuration** (default 3), not via a CLI flag.
+
+A run is "blocked" only by `critical` or `major` issues; `minor`/`suggestion` issues do
+not hold up the loop.
+
+## Pipeline Composer
+
+The phases above are the **default** pipeline. The **Pipeline Composer** (a view
+in the web UI) lets you compose your own: drag agents onto a canvas to build
+**sequential steps**, **parallel groups** (a step with more than one agent runs
+concurrently), and **feedback loops** (an agent that emits a verdict can loop
+back to an earlier step until it passes or hits a cycle cap). Save a layout by
+name and it becomes selectable from **New Pipeline**, where you also pick each
+agent's model/effort and each loop's cycle count.
+
+The engine is data-driven: it executes whatever workflow you select. The default
+workflow reproduces exactly the `Plan → Refine → Implement → Review` behavior
+described above, and **Reset to default** on the canvas redraws it. Workflow topology and
+per-project model/effort/cycle choices are stored in the central SQLite database
+(`~/.worca-cc/worca-cc.db`) — no longer in `~/.worca-cc/workflows/` or
+`<projectDir>/.worca-cc/config.json`.
+
+To add a new agent to the palette, see [`docs/ADDING-AGENTS.md`](docs/ADDING-AGENTS.md).
+
+---
+
+## Guardrails (per run)
+
+Guardrails are **named sets**, selected **per pipeline run**. The **Guardrails**
+view lists the built-ins — **Permissive**, **Normal**, **Strict** — alongside
+your own sets ("Create guardrails" starts from any of them, or blank), with an
+editor for the five policy fields (honor project settings, env scrub, env
+allowlist, protected paths, deny rules). The New Pipeline form has a
+**Guardrails** picker next to the workflow picker: the selected set is the
+run's entire policy, applied uniformly to every agent the run spawns — and,
+for a workspace run, uniformly to every member project.
+
+**Guardrails apply per run; runs without a selection run unguarded
+(Permissive).** The picker defaults to Permissive — no restrictions,
+byte-identical to runs before guardrails existed — so protection is an
+explicit per-run choice, not a persistent project property. (This is a
+deliberate tradeoff of the per-run model: there is no per-project default to
+fall back on, and one set applies to all workspace members. If you want a
+stricter habitual posture, pick Normal/Strict — or your org set — when you
+start the run.)
+
+The built-in tiers:
+
+- **Permissive** (default) — no restrictions; byte-identical behavior to a
+  run with no selection.
+- **Normal** — protects credential files (`.env*`, `*.pem`, `*.key`, SSH keys,
+  cert stores) from agent Read/Edit and blocks publication commands
+  (`git push`, `npm/yarn/pnpm publish`). Never breaks a pipeline: commits,
+  installs, tests, and `curl localhost` all still work.
+- **Strict** (wire id `secure`) — Normal plus: environment scrub on agent
+  spawn (the spawned `claude` gets a minimal env: base vars, the proxy/CA
+  connectivity vars, every `ANTHROPIC_*`/`CLAUDE_*` var, and the set's
+  allowlist — nothing else), network egress binaries denied (`curl`, `wget`,
+  `nc`, `ssh`, `scp`, `rsync`, ...), `gh`/`docker push` and cloud CLIs
+  (`aws`, `gcloud`, `az`) denied, `WebFetch`/`WebSearch` denied, and home-dir
+  credential stores (`~/.ssh`, `~/.aws`, `~/.config/gh`,
+  `~/.git-credentials`, ...) protected from the Read/Edit tools.
+
+Built-ins resolve from worca's code at read time (never snapshotted), so
+preset improvements ship with upgrades; your named sets resolve by reference
+at read time too — editing a set applies to every future run that picks it,
+and to paused runs on resume. Built-ins are undeletable; editing one offers
+"Save as new set". A set pinned by a paused run cannot be deleted (the API
+answers 409 with the pinning runs); finished runs record the set id in
+History and `run.json` (`guardrails.guardrailsId` beside the compact
+envScrub/deny/protected counts — an id, not a content snapshot, since sets
+stay editable). Resume re-reads the set by id and enforces its latest
+definition; a set missing at resume is a LOUD warn in the run log and the
+run proceeds Permissive (fail-open).
+
+How it's enforced: protected paths and deny rules become Claude Code
+`permissions.deny` rules in a single `--settings` payload on every pipeline
+spawn (deny rules merge across scopes and cannot be removed by lower scopes —
+repo settings can't undo worca policy, plugin-granted tools remain subject to
+it). Protected paths expand to `Read(p)` + `Edit(p)` denies (Edit covers
+Write/NotebookEdit; a `Write(p)` rule is never consulted and only produces
+CLI warnings, so it is not emitted). A workspace run enforces the run's ONE
+selected set uniformly on every member — nothing is unioned across member
+projects anymore — and the workspace scanner is not subject to guardrails at
+all (a scan takes no guardrails selection and spawns permissive). Repo
+`.claude/settings.json` `permissions` are honored: natively on
+single-project runs (cwd is the project worktree — the toggle can only decide
+whether they're *lifted*, it cannot un-load what the worktree loads itself);
+on **detached workspace runs (the default)** each member's own `deny` rules
+are lifted per-member into the merged `--settings` when the run's set honors
+project settings (that honor flag is uniform across members now — it comes
+from the selected set, not from each project; `allow`/`ask` rules are never
+lifted — that would widen capability and bypass Claude Code's workspace-trust
+gate; hooks and statusline still don't apply off-worktree and stay warned). A
+paused run re-reads its selected set by id on resume, so it enforces the set's
+latest definition.
+
+Honest limitations:
+- `Read` denial is the load-bearing secret guard; Claude Code does not consult
+  `Write(path)` rules (so worca emits `Read`+`Edit` only), and Bash denies are
+  prefix matches — `sh -c "curl …"`, `/usr/bin/curl`, and `git -c k=v push`
+  evade them (a leading `VAR=val` or a `timeout`/`nice` wrapper does *not*).
+  Env scrub is the real exfil control, but it is **not containment**: with
+  `HOME` retained, credential *files* stay readable to any subprocess an agent
+  spawns (`node -e` + `fetch`), so deny rules alone don't stop indirect reads —
+  for OS-level enforcement use Claude Code's sandbox (out of scope here).
+- Env scrub failing a pipeline that needed an unlisted var fails visibly
+  (tool errors in the transcript) — add the var to the allowlist; there is no
+  silent fallback. Common cases: a corporate TLS-intercepting proxy already
+  survives (proxy/CA vars are kept), but **Bedrock/Vertex/Foundry auth needs
+  you to allowlist the cloud credential vars** (`AWS_*`,
+  `GOOGLE_APPLICATION_CREDENTIALS`, `AZURE_*`), and a run that needs
+  git-over-SSH or takes its git identity from the environment must allowlist
+  `SSH_AUTH_SOCK` / the relevant `GIT_*` names — neither is in the base
+  keep-list. Worca deliberately does **not** set the CLI's own
+  `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` marker: on current CLIs setting it forces
+  the child's permission mode back to `default`, overriding worca's
+  `--permission-mode acceptEdits` and breaking scrubbed pipeline runs.
+- Not setting that marker is not the same as blocking it: if **your own shell**
+  exports `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`, it survives the scrub (the
+  `CLAUDE_*` keep-rule passes it through) and inflicts exactly the breakage
+  above on every spawned `claude` — unset it before launching worca, or expect
+  degraded runs.
+- Strict denies `curl`, which the manual web-UI-testing agent uses to poll a
+  dev server — it falls back to the `browser_*` MCP tools (not denied), so that
+  flow degrades rather than breaks. `.env*` also matches `.env.example` /
+  `.env.sample`, which agents may legitimately edit; a deny list can't carve
+  per-file exceptions, so those become read-only under Normal/Strict too.
+- Exempt from scrub/deny: UI-triggered utility agents outside pipeline runs
+  (overview generation, agent generation), the `graphify` graph-build
+  subprocess, **workspace scans**, and the `claude --help`/`--version`
+  capability probe. In-run title generation IS scrubbed.
+
+---
+
+## Artifact layout
+
+Worca CC keeps **structured state** (projects, workspaces, workflows, per-project config,
+run state + steps + audit events, clarify Q&A, review verdicts) in a single **SQLite
+database**, and the agents' **markdown** outputs (+ any attachments) in a machine-wide
+**external store**. Neither lives in your project's working tree, so nothing is ever
+committed to your repo:
+
+```
+<worcaHome>/                            default ~/.worca-cc
+  settings.json                         { root } only — the bootstrap that locates the DB
+  worca-cc.db  (+ -wal, -shm)           ALL structured state (SQLite, WAL mode)
+  backup-<ts>/                          legacy JSON archived on first upgrade (see below)
+  store/<projectKey>/
+    plans/      <DD-MM-YY>-<name>.md, -v2.md, ...   (plan markdown + refinements)
+    reviews/    <DD-MM-YY>-<name>-impl-review.md     (review markdown)
+    pipelines/  <DD-MM-YY>-<slug>-<id>/              (one folder per run)
+      prompt.md          the prompt text (or copied markdown brief)
+      extras/            any optional extra files you attached
+```
+
+Everything that used to be a per-run `.json`/`.md` control file —
+`clarify.json`, `clarify-answers.json`, `*-review-cycleN.json`, `state.json`,
+`pipeline.md`, plus `meta.json` and the per-project `config.json` and global
+`workflows/*.json` — is now a **row in `worca-cc.db`** instead. Only the plan/review
+**markdown**, `prompt.md`, and `extras/` remain on disk (their existence is indexed in the
+database).
+
+- **`<worcaHome>`** = `<base>/.worca-cc`, where `<base>` is `WORCA_HOME` if set, else
+  the persisted "Worca CC root folder" from Settings, else your OS home. By default this is
+  `~/.worca-cc`, so the DB is `~/.worca-cc/worca-cc.db` and the store is `~/.worca-cc/store/`.
+- **`<projectKey>`** = `<repo-basename-slug>-<sha1(canonicalRoot)[:8]>`, derived from the
+  repository's identity (the parent of its shared `.git`). It is **stable across all git
+  worktrees of the same repo**, so every worktree shares one history.
+
+**First-launch migration.** The first time you run this version, Worca CC imports any
+pre-existing JSON state **found under `~/.worca-cc`** into `worca-cc.db` (in a single
+transaction) and moves the consumed files into a timestamped `~/.worca-cc/backup-<ts>/`
+directory (mirroring the old layout); this is one-way — the new version reads only the
+database, so to roll back you stop Worca CC, restore the files from `backup-<ts>/`, and
+downgrade. There is **no** migration from the pre-rebrand home directory that older,
+differently-named releases used: this version only ever looks at `~/.worca-cc`, so if you
+are upgrading you must move your old state there **by hand before the first launch** —
+otherwise Worca CC simply starts up empty, with no warning. (Separately, any very old
+`<projectDir>/ai-artifacts/` directories from before the external-store change are still
+just left in place and ignored.)
+
+Because state is machine-wide and keyed by repo identity, the web UI has an **"All
+projects"** view (and `GET /api/history`) that lists runs across every project on the
+machine — now backed by indexed SQL queries instead of a directory scan.
+
+The exact table contracts are specified in `docs/ARCHITECTURE.md` §5.
+
+---
+
+## Project structure
+
+```
+src/core/        protocol, store, artifacts, preflight, claude-runner, phases, orchestrator
+src/cli/         worca-cc.mjs (CLI entry)
+scripts/         install.mjs (copy agents + skill into a target project)
+agents/          agent prompts + .meta.json sidecars (data-driven set)
+skills/          worca/SKILL.md (the /worca skill)
+ui/              server.mjs + public/ (single-page web UI)
+docs/            ARCHITECTURE.md (single source of truth)
+```
+
+Generated plans, reviews, and pipeline run folders are **not** part of this repo: they
+live in the machine-wide external store at `<worcaHome>/store/<projectKey>/` (default
+`~/.worca-cc/store/...`). See [Artifact layout](#artifact-layout).

package/agents/clarify.meta.json

@@ -0,0 +1,19 @@
+{
+  "key": "clarify",
+  "domain": "coding",
+  "displayName": "Clarify",
+  "description": "Turns hidden decisions into questions before planning. Multiple-choice, so later steps never guess.",
+  "color": "red",
+  "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,
+  "order": 0
+}

package/agents/decomposer.meta.json

@@ -0,0 +1,21 @@
+{
+  "key": "decomposer",
+  "domain": "coding",
+  "displayName": "Decompose",
+  "description": "Splits an approved plan into vertical-slice tasks. Each task gets its own implementer.",
+  "color": "blue",
+  "scope": "project",
+  "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,
+  "order": 2.5
+}

package/agents/implementer.meta.json

@@ -0,0 +1,20 @@
+{
+  "key": "implementer",
+  "domain": "coding",
+  "displayName": "Implementation",
+  "description": "Writes the code from the approved plan, strict TDD. In fix mode, addresses only the issues a review flagged.",
+  "color": "peach",
+  "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,
+  "order": 3
+}

package/agents/manualTestsChecklist.meta.json

@@ -0,0 +1,18 @@
+{
+  "key": "manualTestsChecklist",
+  "domain": "coding",
+  "displayName": "Manual Tests Checklist",
+  "description": "Drafts a manual test checklist for the change. User-visible flows, edge cases, regressions worth clicking through.",
+  "color": "blue",
+  "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,
+  "order": 5
+}

package/agents/manualWebUiTesting.meta.json

@@ -0,0 +1,18 @@
+{
+  "key": "manualWebUiTesting",
+  "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.",
+  "color": "violet",
+  "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,
+  "order": 6
+}

package/agents/planReviewer.meta.json

@@ -0,0 +1,19 @@
+{
+  "key": "planReviewer",
+  "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.",
+  "color": "amber",
+  "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,
+  "order": 7
+}

package/agents/planner.meta.json

@@ -0,0 +1,20 @@
+{
+  "key": "planner",
+  "domain": "coding",
+  "displayName": "Plan",
+  "description": "Explores the codebase and writes the implementation plan. Architecture, task breakdown, concrete code snippets; can ask clarifying questions first.",
+  "color": "violet",
+  "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,
+  "order": 1
+}

package/agents/refiner.meta.json

@@ -0,0 +1,19 @@
+{
+  "key": "refiner",
+  "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.",
+  "color": "green",
+  "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,
+  "order": 2
+}

package/agents/reviewer.meta.json

@@ -0,0 +1,19 @@
+{
+  "key": "reviewer",
+  "domain": "coding",
+  "displayName": "Review Implementation",
+  "description": "Reviews the implementation diff against the plan. Honest verdict; blocking findings loop back to the implementer.",
+  "color": "blue",
+  "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,
+  "order": 4
+}

package/agents/worca-cc-clarify.md

@@ -0,0 +1,67 @@
+---
+name: worca-cc-clarify
+description: Clarify agent for the orchestrator pipeline. Before planning, surfaces the open decisions the planner cannot safely resolve from the task text or the real codebase — including things downstream agents would otherwise silently assume — as conceptual questions with 2–4 options + a free-text fallback, written to clarify.json. Asks nothing it can determine itself; empty when the task is unambiguous. Invoked by the deterministic orchestrator, never directly by a human.
+tools: Read, Write, Edit, Bash, Grep, Glob, Skill
+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.
+
+## 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.
+
+## What to do
+
+The task prompt gives you the user's task/prompt (and any attached markdown / extra files), and the pipeline directory where you must write `clarify.json`.
+
+1. Read the task and explore the target codebase enough to understand context (see Fan-out and Graph tooling below).
+2. Identify ONLY the few highest-impact decisions you cannot resolve. Turn each into a single, conceptual, decision-shaped question.
+
+Rules for questions:
+- Each question targets ONE real ambiguity that changes the plan. Skip anything you can determine for certain from the codebase or the task text.
+- Phrase conceptually (about intent, scope, behavior, trade-offs), not about trivia you can look up.
+- Provide **2–4** distinct, plausible `options` (short strings), ordered most-likely first when there is a sane default. Use just 2 for a genuine binary; never pad with filler choices.
+- Every question allows free text: set `allowFreeText: true`.
+- Give each question a short stable `id` (kebab-case, e.g. `auth-storage`, `error-format`).
+- Ask as many questions as there are genuinely material, unresolved decisions, **up to 8**. Prefer fewer when fewer will do — surfacing a real hidden assumption is good; padding the list with low-value questions is not. Never split one decision into several questions. If the task is unambiguous or the codebase answers it, write an EMPTY questions array — never fabricate questions.
+
+Write `clarify.json` to the pipeline directory given in the prompt, EXACTLY in this shape (no extra keys, no prose, no code fences around the file content):
+
+```json
+{
+  "questions": [
+    {
+      "id": "auth-storage",
+      "question": "Where should sessions be stored?",
+      "options": ["Redis", "Postgres", "In-memory"],
+      "allowFreeText": true
+    },
+    {
+      "id": "delete-behavior",
+      "question": "Should delete be a hard delete or a soft delete?",
+      "options": ["Hard delete", "Soft delete"],
+      "allowFreeText": true
+    }
+  ]
+}
+```
+
+If nothing needs clarification:
+
+```json
+{ "questions": [] }
+```
+
+Then stop. Emit a brief assistant note saying how many questions you wrote and the absolute path of `clarify.json`. Do NOT write a plan — that is the Planner's job.
+
+## Fan-out (parallel sub-agents)
+The orchestrator decides per run whether you may fan out. When enabled, your task prompt carries a `## Fan-out ENABLED` block AND the Task/Agent tool is in your tool list. In that case, dispatch ONE read-only research sub-agent per independent area (UI vs server vs store vs tests) IN PARALLEL (`subagent_type: "general-purpose"`, or `"Explore"` for pure code search), then synthesize. Sub-agents are strictly READ-ONLY; **YOU** write `clarify.json`. Skip fan-out for a trivial task or when it is not enabled.
+
+## Output contract reminders
+- `clarify.json` shape is fixed and consumed by `protocol.readClarify`; keep it byte-clean (valid JSON, `allowFreeText` always `true`, `options` an array of **2–4** short strings).
+- Write with the absolute path taken from the prompt. Never write outside the pipeline dir.
+- Keep assistant chatter minimal; your real output is the file you write.
+
+## Graph tooling
+A grounding tool may be offered in the prompt. If the prompt says **graphify** is available, use graphify to query/understand the codebase first (invoke via the `Skill` tool when it says skill, run via Bash when it says CLI, or read `graphify-out/` when it says cached). Else if it says **code-review-graph** is available, use that (CLI via Bash). If BOTH, ALWAYS use graphify. If NEITHER, use Glob/Grep/Read directly.