@worca/app 0.0.1

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

@@ -0,0 +1,56 @@
+---
+name: worca-cc-workspace-reviewer
+description: Workspace Reviewer for the orchestrator pipeline. On a workspace run it replaces the single-project Code Reviewer: it fans out one reviewer sub-agent per CHANGED member project (each diffing that project's checkpoint...feature inside its own worktree), then synthesizes ONE review markdown and ONE review-cycleN.json that is the UNION of every critical/major issue across all members, sorted by projectKey then severity. Drives the workspace review -> implementer loop. Invoked by the deterministic orchestrator.
+tools: Read, Write, Edit, Bash, Grep, Glob, Skill
+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.
+
+## What to do (review-fanout, cap 8)
+
+1. **Fan out one reviewer per TOUCHED member.** Dispatch ONE reviewer sub-agent per member project whose `checkpointRef...feature` diff is non-empty — SKIP any project whose diff against its checkpoint is empty. Each sub-agent cwds into that project's named worktree, inspects its `git diff <checkpointRef>` (plus `git status`, since new files are intent-to-added and DO appear in the diff), judges it against the plan, and reports issues with severities critical|major|minor|suggestion.
+2. **Synthesize ONE verdict yourself.** Fold every per-project review into a SINGLE review markdown AND a SINGLE `review-cycleN.json`. The issue list is the **UNION of every critical/major issue across all members — never collapse, merge, or drop one**. Sort issues by `projectKey` ascending, then by severity (critical before major before minor before suggestion). Prefix every issue `location` with `"<projectKey>: "` so a reader can tell which member it belongs to.
+3. If NO project changed (every diff empty), emit a clean verdict: `{ "issues": [], "summary": "..." }` — do not crash on an empty fan-out set.
+
+## Anti-explosion rule (binding)
+Sub-agents are strictly single-level: a reviewer sub-agent MUST NOT re-fan-out (it must never spawn its own Task/Agent sub-agents). YOU synthesize the merged review markdown + verdict JSON yourself.
+
+## review-cycleN.json contract (consumed by protocol.readReview / hasBlocking)
+
+```json
+{
+  "issues": [
+    {
+      "severity": "critical",
+      "title": "Short imperative summary",
+      "detail": "What is wrong, where, why it matters, and the concrete fix.",
+      "location": "<projectKey>: path/to/file.ext:line or function/area"
+    }
+  ],
+  "summary": "1-3 sentence verdict on the implementation across all member projects versus the plan."
+}
+```
+
+Severity definitions (use them honestly):
+- **critical** — broken behavior, security hole, failing/absent core tests, or a regression; MUST be fixed.
+- **major** — significant correctness/quality/conformance problem; should be fixed before acceptance.
+- **minor** — small issue; non-blocking.
+- **suggestion** — optional improvement.
+
+`critical` and `major` are blocking; the loop continues (Implementer fixes, you re-review) until none remain across EVERY member. Report `[]` with a positive summary only when every touched project's diff genuinely matches the plan and is correct, tested, and clean.
+
+After writing both files, emit a short assistant note with the absolute paths of the review markdown and the review JSON, and the total count of critical/major issues across all members.
+
+## Output contract reminders
+- The review JSON must be valid and match the shape above (`severity` from {critical, major, minor, suggestion}); it is parsed by `safeParseJson` / `readReview`.
+- Base findings on the real per-project `git diff`, not assumptions. Write only to the two absolute paths given. Never collapse the per-project unions into a single deduped issue.
+- Keep prose in the assistant message minimal; the merged markdown + JSON are your real output.
+
+## Graph tooling
+If the prompt says **graphify** is available, use graphify to ground the review in each member's codebase, following the exact dispatch mechanism the system-prompt instruction specifies (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 it (CLI via Bash). If BOTH are mentioned, ALWAYS use graphify. If NEITHER is available, proceed without, inspecting each real project with git + Glob/Grep/Read.

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

@@ -0,0 +1,55 @@
+---
+name: worca-cc-workspace-scanner
+description: Workspace Scanner for the Worca CC wizard. Investigates the cross-project interconnections of a set of 2+ onboarded repos (REST APIs, shared DB/migrations, build deps, message queues, shared libs) by fanning out one read-only investigator per project, then synthesizes ONE editable interconnection description against a fixed template. Read-only; never edits any member repo. Off-pipeline — invoked directly by the workspace scan engine, not by the deterministic dispatcher.
+tools: Read, Write, Bash, Grep, Glob, Skill
+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.
+
+## What to do
+
+1. **Fan out (scan-fanout, cap 8).** Dispatch ONE read-only investigator sub-agent per member project. Each investigator surveys ITS project's public surface — exposed REST routes/clients, DB schemas + migrations, message/queue producers and consumers, shared libraries and build dependencies — and reports the project's OUTWARD relations to the other named members. For relation discovery use ordered project pairs `(A -> B)`: all pairs for <=4 projects, star-from-each for >=5. Announce each investigation with a line `INVESTIGATING <projectKey> relations to <otherKey>` so the wizard's live status updates; announce the merge with `SYNTHESIZING workspace description`.
+2. **Ground in the real code.** When a project has `graphify-out/`, read `graphify-out/GRAPH_REPORT.md` and run `graphify query`/`explain`/`path` to find cross-project symbol overlap. Otherwise inspect the source directly with `Read`/`Grep`/`Glob`. If a project's graph is missing or its build failed, degrade that project to source-reading — never abort the scan over one project.
+3. **Synthesize ONE description yourself.** Collect every investigator report, merge them in sorted `projectKey` order (never completion order), and write a single markdown string to the given path following the template below. Include every discovered relation; completeness beats brevity, but stay dense (see the length budget below).
+
+## Anti-explosion rule (binding)
+Sub-agents are strictly single-level: an investigator MUST NOT re-fan-out (it must never spawn its own Task/Agent sub-agents). YOU synthesize the merged description yourself.
+
+## Interconnection description template (write EXACTLY these sections)
+
+```
+# Workspace: <name>
+## Overview
+<2-4 sentences: what the project set is and the dominant integration theme>
+## Projects
+- <projectName>: <one-line role>
+## Interconnections
+- <A> -> <B>: <relation kind: REST API | shared DB / migration | build dep | message/queue | shared lib>; <1-line detail>
+## Change-coordination notes
+- <e.g. "UI changes consult update-server API docs">
+## Suggested change order
+<topological hint when dependencies imply ordering, else "no strict ordering">
+```
+
+## Length & completeness (soft budget — no hard cap)
+Capture EVERY real interconnection you found — every relation pair, each with its kind and a concrete one-line detail — plus the few facts an agent needs to navigate the set. There is NO character or line limit and nothing downstream truncates your output, so never abbreviate a section and never end with "…": write the whole thing.
+
+Scale the length to the workspace, do not pad to a target:
+- A small / simple set (2–3 projects, few relations) stays short — often well under ~100 lines.
+- A large / complex set may reach ~200–300 lines. Treat 200–300 as an UPPER guideline for the most complex workspaces, not a goal to fill.
+
+Prefer dense, project-agnostic prose over filler. NEVER invent a relation to add length, and NEVER drop a real relation to stay short. The description is the editable result the user reviews and saves; it is injected verbatim into every agent on a later workspace run, so keep it grounded in what you actually found.
+
+## Output contract reminders
+- Write ONLY the single description markdown to the absolute path you are given. Edit nothing in any member repo.
+- After writing, emit a short assistant note with the absolute path of the description you wrote.
+- Keep prose in the assistant message minimal; the description markdown is your real output.
+
+## Graph tooling
+If the prompt says **graphify** is available for a project, use graphify to ground the investigation, following the exact dispatch mechanism the system-prompt instruction specifies (invoke via the `Skill` tool when it says skill, run via Bash when it says CLI, or read `graphify-out/` when it says cached). If graphify is unavailable for a project, proceed without it, inspecting the real project with Glob/Grep/Read.

package/agents/workspaceReviewer.meta.json

@@ -0,0 +1,20 @@
+{
+  "key": "workspaceReviewer",
+  "domain": "shared",
+  "displayName": "Workspace Review",
+  "description": "Fans out one review per changed project in the workspace. Synthesizes a single cross-project verdict.",
+  "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=\"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,
+  "order": 4.5,
+  "scope": "workspace-only"
+}

package/agents/workspaceScanner.meta.json

@@ -0,0 +1,18 @@
+{
+  "key": "workspaceScanner",
+  "domain": "shared",
+  "displayName": "Workspace Scan",
+  "description": "Maps how the workspace's projects relate before pipelines run. Shared APIs, schemas, queues, and build dependencies.",
+  "color": "violet",
+  "icon": "<path d=\"M4 7h16M4 12h10M4 17h7\" stroke-linecap=\"round\"/><circle cx=\"18\" cy=\"15\" r=\"3\"/><path d=\"M20.2 17.2L22 19\" stroke-linecap=\"round\"/>",
+  "agentFile": "worca-cc-workspace-scanner.md",
+  "runnerType": "producer",
+  "loopSource": false,
+  "fanOut": true,
+  "produces": ["workspace"],
+  "consumes": ["userPrompt"],
+  "connectsTo": [],
+  "asksQuestions": false,
+  "order": 0.5,
+  "scope": "workspace-only"
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@worca/app",
+  "version": "0.0.1",
+  "description": "Worca — deterministic multi-agent pipeline that drives Claude Code (headless) through Plan -> Refine -> Implement -> Review, with a CLI, an installable /worca skill, and a web UI.",
+  "license": "MIT",
+  "author": "Sinisha Djukic",
+  "type": "module",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SinishaDjukic/worca-cc.git"
+  },
+  "homepage": "https://github.com/SinishaDjukic/worca-cc#readme",
+  "bugs": {
+    "url": "https://github.com/SinishaDjukic/worca-cc/issues"
+  },
+  "keywords": [
+    "worca",
+    "pipeline",
+    "orchestrator",
+    "claude-code",
+    "ai-agents",
+    "autonomous-coding"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "worca": "src/cli/worca-cc.mjs"
+  },
+  "files": [
+    "src/",
+    "ui/server.mjs",
+    "ui/public/",
+    "agents/",
+    "skills/",
+    "scripts/install.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node --disable-warning=ExperimentalWarning ui/server.mjs",
+    "cli": "node --disable-warning=ExperimentalWarning src/cli/worca-cc.mjs",
+    "install:agents": "node scripts/install.mjs",
+    "build:presenter": "node scripts/build-presenter.mjs",
+    "smoke": "WORCA_MOCK=1 WORCA_HOME=.worca-cc-smoke node --disable-warning=ExperimentalWarning src/cli/worca-cc.mjs --project sandbox --prompt \"demo task\" --mock --yes",
+    "smoke:workspace": "WORCA_MOCK=1 WORCA_HOME=.worca-cc-smoke node --disable-warning=ExperimentalWarning scripts/smoke-workspace.mjs",
+    "smoke:plugin": "WORCA_MOCK=1 WORCA_HOME=.worca-cc-smoke node --disable-warning=ExperimentalWarning scripts/smoke-plugin.mjs",
+    "test": "rm -rf .worca-cc-test && WORCA_HOME=.worca-cc-test node --disable-warning=ExperimentalWarning --test test/*.mjs"
+  },
+  "dependencies": {
+    "express": "^4.19.2",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@fontsource/jetbrains-mono": "^5.2.8",
+    "@fontsource/poppins": "^5.2.7",
+    "jsdom": "^29.1.1"
+  }
+}

package/scripts/install.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+// scripts/install.mjs
+//
+// Copy the orchestrator agents and the /worca skill into a target project's
+// .claude directory so that opening Claude Code there lets the user run:
+//   /worca <prompt>
+//
+// Usage:
+//   node scripts/install.mjs <targetDir> [--force]
+//
+// - agents/*.md            -> <targetDir>/.claude/agents/
+// - skills/worca/**        -> <targetDir>/.claude/skills/worca/
+//
+// Without --force, existing files are left untouched (and reported as skipped).
+// ESM, no external dependencies.
+
+import { readdir, mkdir, copyFile, stat, access, readFile, writeFile } from 'node:fs/promises';
+import { constants as FS } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve, join, relative } from 'node:path';
+import process from 'node:process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const REPO_ROOT = resolve(__dirname, '..');
+const AGENTS_SRC = join(REPO_ROOT, 'agents');
+const SKILL_SRC = join(REPO_ROOT, 'skills', 'worca');
+
+function parseArgs(argv) {
+  const out = { target: null, force: false, help: false };
+  for (const arg of argv) {
+    if (arg === '--force' || arg === '-f') out.force = true;
+    else if (arg === '--help' || arg === '-h') out.help = true;
+    else if (!arg.startsWith('-') && !out.target) out.target = arg;
+  }
+  return out;
+}
+
+const HELP = `install — copy orchestrator agents + /worca skill into a project
+
+Usage:
+  node scripts/install.mjs <targetDir> [--force]
+
+Copies:
+  agents/*.md            -> <targetDir>/.claude/agents/
+  skills/worca/**        -> <targetDir>/.claude/skills/worca/
+
+Options:
+  --force, -f   Overwrite files that already exist
+  --help, -h    Show this help
+`;
+
+async function exists(p) {
+  try {
+    await access(p, FS.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Copy a single file, honoring --force. Returns "copied" | "skipped".
+ */
+async function copyOne(src, dest, force) {
+  await mkdir(dirname(dest), { recursive: true });
+  if (!force && (await exists(dest))) {
+    return 'skipped';
+  }
+  await copyFile(src, dest);
+  return 'copied';
+}
+
+/**
+ * Recursively copy a directory tree. Returns counts { copied, skipped }.
+ */
+async function copyTree(srcDir, destDir, force) {
+  const counts = { copied: 0, skipped: 0 };
+  let entries;
+  try {
+    entries = await readdir(srcDir, { withFileTypes: true });
+  } catch {
+    return counts;
+  }
+  for (const ent of entries) {
+    const src = join(srcDir, ent.name);
+    const dest = join(destDir, ent.name);
+    if (ent.isDirectory()) {
+      const sub = await copyTree(src, dest, force);
+      counts.copied += sub.copied;
+      counts.skipped += sub.skipped;
+    } else if (ent.isFile()) {
+      const r = await copyOne(src, dest, force);
+      counts[r] += 1;
+    }
+  }
+  return counts;
+}
+
+/**
+ * Rewrite the `<WORCA_REPO>` placeholder in the installed SKILL.md to the real
+ * absolute path of this orchestrator repo, so /worca works on the target
+ * machine without manual editing. Best-effort: never fails the install.
+ * @returns {Promise<boolean>} true if the file was rewritten.
+ */
+async function rewriteSkillRepoPath(skillDest, repoRoot) {
+  const skillMd = join(skillDest, 'SKILL.md');
+  try {
+    const original = await readFile(skillMd, 'utf8');
+    const rewritten = original.split('<WORCA_REPO>').join(repoRoot);
+    if (rewritten !== original) {
+      await writeFile(skillMd, rewritten, 'utf8');
+      return true;
+    }
+  } catch {
+    /* no SKILL.md or unreadable — skip */
+  }
+  return false;
+}
+
+function log(s) {
+  process.stdout.write(s + '\n');
+}
+
+async function main() {
+  const { target, force, help } = parseArgs(process.argv.slice(2));
+  if (help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (!target) {
+    process.stderr.write('install: missing <targetDir>. See --help.\n');
+    return 2;
+  }
+
+  const targetDir = resolve(target);
+  if (!(await exists(targetDir))) {
+    process.stderr.write(`install: target directory does not exist: ${targetDir}\n`);
+    return 2;
+  }
+  const targetStat = await stat(targetDir);
+  if (!targetStat.isDirectory()) {
+    process.stderr.write(`install: target is not a directory: ${targetDir}\n`);
+    return 2;
+  }
+
+  const claudeDir = join(targetDir, '.claude');
+  const agentsDest = join(claudeDir, 'agents');
+  const skillDest = join(claudeDir, 'skills', 'worca');
+
+  log(`Installing worca-cc into: ${targetDir}`);
+  if (force) log('(--force: existing files will be overwritten)');
+
+  // Agents: copy only the *.md files.
+  let agentEntries = [];
+  try {
+    agentEntries = (await readdir(AGENTS_SRC, { withFileTypes: true }))
+      .filter((e) => e.isFile() && e.name.endsWith('.md'))
+      .map((e) => e.name);
+  } catch {
+    agentEntries = [];
+  }
+
+  const agentCounts = { copied: 0, skipped: 0 };
+  if (agentEntries.length === 0) {
+    log(`! No agent markdown files found in ${relative(REPO_ROOT, AGENTS_SRC) || AGENTS_SRC}.`);
+  } else {
+    await mkdir(agentsDest, { recursive: true });
+    for (const name of agentEntries) {
+      const r = await copyOne(join(AGENTS_SRC, name), join(agentsDest, name), force);
+      agentCounts[r] += 1;
+      log(`  ${r === 'copied' ? '+' : '='} agents/${name}`);
+    }
+  }
+
+  // Skill: copy the whole skills/worca tree.
+  let skillCounts = { copied: 0, skipped: 0 };
+  if (await exists(SKILL_SRC)) {
+    skillCounts = await copyTree(SKILL_SRC, skillDest, force);
+    log(`  ${skillCounts.copied ? '+' : '='} skills/worca/ (${skillCounts.copied} copied, ${skillCounts.skipped} skipped)`);
+    // Personalize the copied skill so /worca targets this repo's real path.
+    if (await rewriteSkillRepoPath(skillDest, REPO_ROOT)) {
+      log(`  ~ skills/worca/SKILL.md (rewrote <WORCA_REPO> -> ${REPO_ROOT})`);
+    }
+  } else {
+    log(`! Skill source not found at ${relative(REPO_ROOT, SKILL_SRC) || SKILL_SRC}.`);
+  }
+
+  log('');
+  log(
+    `Done. Agents: ${agentCounts.copied} copied / ${agentCounts.skipped} skipped. ` +
+      `Skill: ${skillCounts.copied} copied / ${skillCounts.skipped} skipped.`,
+  );
+  if (!force && (agentCounts.skipped > 0 || skillCounts.skipped > 0)) {
+    log('Some files already existed and were skipped. Re-run with --force to overwrite.');
+  }
+  log('');
+  log('Next step: open Claude Code in that project and run:');
+  log('  /worca <your task prompt>');
+
+  return 0;
+}
+
+main()
+  .then((code) => process.exit(code ?? 0))
+  .catch((err) => {
+    process.stderr.write(`install: fatal: ${err?.stack || err?.message || err}\n`);
+    process.exit(1);
+  });

package/skills/worca/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: worca
+description: Run the deterministic multi-agent orchestrator (Plan -> Refine -> Implement -> Review) over a software task in the current project. Triggers on "/worca", "/worca <prompt>", "/worca --ui", and on requests to orchestrate, run the orchestration pipeline, or drive Claude Code through plan/refine/implement/review for a task.
+---
+
+# Orchestrate
+
+Drive the current project through the orchestrator pipeline: **Preflight -> Plan -> Refine (loop) -> Implement -> Review (loop) -> Done**. Orchestration is performed by a deterministic Node.js script; this skill just launches it. Artifacts (plans, reviews, pipeline audit logs) are written under `ai-artifacts/` in the project.
+
+The orchestrator repo lives wherever it was installed. `<WORCA_REPO>` below is the absolute path of that repo (the directory containing `src/cli/worca-cc.mjs`). If you installed via `scripts/install.mjs`, the installer rewrites `<WORCA_REPO>` in this file to the real path automatically; otherwise substitute it yourself (or set an `WORCA_REPO` environment variable and use `"$WORCA_REPO"`).
+
+## /worca <prompt> — run the pipeline (default action)
+
+When invoked as `/worca <prompt>`, run the CLI with the user's text as the prompt and the user's current project as the working directory:
+
+```bash
+node <WORCA_REPO>/src/cli/worca-cc.mjs --project "$PWD" --prompt "<args>"
+```
+
+- `--project "$PWD"` — operate inside the user's current project (the orchestrator does all file writes here).
+- `--prompt "<args>"` — everything the user typed after `/worca`. Quote it.
+- The CLI streams phase changes and live agent logs to the terminal. When the clarify step needs a decision it shows each question's 2–4 options plus a free-text field; when a refine/review loop hits its cap it shows the open critical/major issues and asks whether to continue or approve another cycle. Answer interactively.
+- On completion it prints the pipeline directory under `ai-artifacts/pipelines/`.
+
+Useful flags (pass through when the user asks):
+- `--file <path.md>` — use a markdown file as the prompt instead of `--prompt`.
+- `--title "<name>"` — label the pipeline.
+- `--max-refine <N>` / `--max-review <N>` — change loop caps (default 5 each).
+- `--model <m>` / `--permission-mode <m>` — Claude model / permission mode (default `acceptEdits`).
+- `--mock` — run the full pipeline offline with canned agents (no Claude spawn, no tokens); great for a dry run. Equivalent to setting `WORCA_MOCK=1`.
+- `--yes` / `--non-interactive` — auto-answer (clarify picks the first option; gates choose "continue"). Use for unattended runs.
+
+Example:
+
+```bash
+node <WORCA_REPO>/src/cli/worca-cc.mjs \
+  --project "$PWD" --prompt "Add rate limiting to the public API"
+```
+
+## /worca --ui — launch the web UI
+
+To start the web app (new-pipeline form, step tracker, live log window, question + loop-gate panels, Stop button, run history):
+
+```bash
+node <WORCA_REPO>/src/cli/worca-cc.mjs --ui
+```
+
+This starts `ui/server.mjs` (Express + WebSocket, default port `4317`; set `PORT` to change). Open the printed URL in a browser. In the UI you pick the project folder to operate in, supply a prompt OR a markdown document (plus optional extra files), optionally toggle mock mode, and Start. The UI also has an "Install agents into this folder" button.
+
+## Installing the agents + skill into another project
+
+So a teammate can open Claude Code in their own repo and type `/worca <prompt>`, copy the agents and this skill into that project's `.claude/`:
+
+```bash
+node <WORCA_REPO>/scripts/install.mjs "<targetDir>"
+```
+
+- Copies `agents/*.md` into `<targetDir>/.claude/agents/` and `skills/worca/` into `<targetDir>/.claude/skills/worca/`.
+- Add `--force` to overwrite existing copies.
+- Prints a next-step hint. After installing, open Claude Code in `<targetDir>` and run `/worca <prompt>`.
+- You can also trigger this from the CLI (`--install <targetDir>`) or the UI ("Install agents into this folder").
+
+## Notes
+- The orchestrator auto-initializes a git repo in the target project (initial commit) if none exists, so the reviewer can diff the implementation.
+- Preflight auto-detects `graphify` and `code-review-graph`; if both are present it always uses graphify and tells the agents to ground their work in it.
+- Prefer `--mock` first if you just want to see the pipeline run end-to-end without spending tokens.