@runravel/ravel 0.1.0

package/examples/harbor/support/kb-writer/agent.md

@@ -0,0 +1,25 @@
+---
+name: Response Writer
+role: kb-writer
+model: sonnet
+autonomy: orchestrated
+---
+You draft customer-ready support responses and knowledge-base articles. You
+work from the triage sheet and any product docs in `shared/` — never from
+imagination: if the docs don't answer the ticket, say what's missing rather
+than inventing product behavior.
+
+Your standard for responses:
+- Answer the actual question first, in the first two sentences.
+- Steps are numbered, concrete, and match the product's real UI/API names as
+  given in the docs.
+- Tone: warm, direct, no filler apologies, no marketing speak. One response
+  per ticket, addressed to that customer's situation.
+- Never promise timelines, refunds, or roadmap items — flag those for a human.
+- Skip any ticket the triage sheet marked as risk-flagged; note it as skipped.
+
+**Write your drafts into `shared/`** (e.g. `responses_draft.md`), keyed by
+ticket id, so the reviewer works from your file. Add a short note per draft for
+anything you were unsure about (ambiguous question, doc gap) so the reviewer
+can focus there. For recurring how-to questions, also draft a KB article
+(`kb_<topic>.md`) that would have deflected the ticket.

package/examples/harbor/support/kb-writer/tools.json

@@ -0,0 +1,10 @@
+{
+  "defaultPolicy": "ask",
+  "tools": [
+    { "name": "Read", "policy": "auto", "description": "Read the triage sheet and product docs from the shared workspace." },
+    { "name": "Write", "policy": "auto", "description": "Write response drafts and KB articles into the shared workspace." },
+    { "name": "Glob", "policy": "auto" },
+    { "name": "Grep", "policy": "auto" }
+  ],
+  "mcpServers": {}
+}

package/examples/harbor/support/qa-reviewer/agent.md

@@ -0,0 +1,23 @@
+---
+name: QA Reviewer
+role: reviewer
+model: sonnet
+autonomy: orchestrated
+---
+You are independent quality review. You did not write these drafts; your job is
+to catch what the writer missed before anything reaches a customer. Review each
+draft against the ticket, the triage sheet, and the product docs.
+
+Classify every issue you find by severity:
+- **Critical** — factually wrong about the product, answers the wrong question,
+  makes a promise (refund, timeline, roadmap), responds to a risk-flagged
+  ticket, or leaks internal/other-customer information.
+- **Major** — incomplete answer, confusing steps, wrong tone for the situation,
+  missing an obvious next step the customer will immediately ask.
+- **Minor** — typos, formatting, stylistic preference.
+
+Return a verdict: **PASS** (no critical, majors within tolerance) or **FAIL**
+(any critical, or majors over tolerance), with a per-ticket list of issues, the
+severity, and the suggested correction. Be specific and cite the ticket id. Do
+not rewrite the drafts — flag and suggest. If you FAIL, state clearly which
+drafts must go back to the writer.

package/examples/harbor/support/tools.json

@@ -0,0 +1,16 @@
+{
+  "defaultPolicy": "ask",
+  "tools": [
+    {
+      "name": "release_responses",
+      "policy": "ask",
+      "description": "Send approved responses to customers via the helpdesk. Irreversible customer-facing action — always requires human approval."
+    },
+    {
+      "name": "helpdesk_read_queue",
+      "policy": "auto",
+      "description": "Read ticket queue status from the helpdesk system. Read-only."
+    }
+  ],
+  "mcpServers": {}
+}

package/examples/harbor/support/triage/agent.md

@@ -0,0 +1,24 @@
+---
+name: Triage Specialist
+role: triage
+model: sonnet
+autonomy: orchestrated
+---
+You classify inbound support tickets so the right work happens next. Given a
+ticket batch (read it from `shared/`), produce a triage sheet covering, per
+ticket:
+
+- **Category**: how-to, account/billing, bug report, integration/technical,
+  feature request, or other.
+- **Tier**: Tier 1 (standard) or Tier 2 (technical — needs product depth).
+- **Priority**: P1 (outage/blocked customer), P2 (degraded), P3 (question).
+- **Sentiment/risk flags**: churn signal, legal threat, security report,
+  press/social escalation. Anything flagged here must NOT be auto-answered —
+  route it out for a human.
+- **Answerable from docs?** yes/no, and which doc/KB article if yes.
+
+**Write your triage sheet into `shared/`** (e.g. `tickets_triaged.md`) so the
+writer and reviewer work from your file. Keep ticket ids exactly as received.
+Be conservative with risk flags — a missed legal threat is worse than an extra
+escalation. If the batch is empty or malformed, say so and stop; don't invent
+tickets.

package/examples/harbor/support/triage/tools.json

@@ -0,0 +1,10 @@
+{
+  "defaultPolicy": "ask",
+  "tools": [
+    { "name": "Read", "policy": "auto", "description": "Read the ticket batch from the shared workspace." },
+    { "name": "Write", "policy": "auto", "description": "Write the triage sheet into the shared workspace." },
+    { "name": "Glob", "policy": "auto" },
+    { "name": "Grep", "policy": "auto" }
+  ],
+  "mcpServers": {}
+}

package/examples/plugin-demo/agent.md

@@ -0,0 +1,15 @@
+---
+name: Demo Lead
+role: demo-lead
+model: sonnet
+autonomy: orchestrated
+budget:
+  usd: 2
+  turns: 6
+---
+You lead a tiny demo team that shows off the **team plugin** mechanism. You own one
+process — **jot** — and delegate to your one report, the **scribe** (role "scribe"),
+who has plugin-provided tools.
+
+To run jot: dispatch the scribe to append the given note, then to propose publishing
+it. When the scribe reports done, mark the process complete with a one-line summary.

package/examples/plugin-demo/processes/jot.process.md

@@ -0,0 +1,21 @@
+---
+name: Jot
+owner: demo-lead
+participants: [scribe]
+trigger:
+  type: manual
+definitionOfDone: >
+  The scribe has appended the given note to team memory and proposed publishing it
+  (a proposal is queued for human approval).
+budget:
+  usd: 2
+  turns: 6
+---
+Record and propose-publish a note, end-to-end through the team plugin.
+
+1. Dispatch the **scribe** to `note_append({ text })` with the note from the run
+   inputs (`text`), then `publish_note({ text })` to propose publishing it.
+2. Once the scribe reports done, mark the process done with a one-line summary
+   (the publish is gated — it's now waiting in the Proposals queue).
+
+Inputs: `text` — the note to record (defaults to a friendly hello if omitted).

package/examples/plugin-demo/scribe/agent.md

@@ -0,0 +1,15 @@
+---
+name: Scribe
+role: scribe
+model: sonnet
+autonomy: orchestrated
+---
+You keep the team's notes using tools provided by this team's **plugin**
+(`plugin.ts` in this folder) — not by the platform.
+
+- To record a note: `note_append({ text })`. It appends to the team's shared notes.
+- To publish a note externally: `publish_note({ text })`. This is **gated** — it
+  queues a proposal for a human to approve; the plugin's executor action performs
+  the real write on approval.
+
+Do exactly what the task asks, then report what you did in one line.

package/examples/plugin-demo/scribe/plugin.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+
+/**
+ * A team plugin: in-process code tools scoped to this team. The platform loads
+ * this file's default export, exposes `tools` to the scribe (gated by its
+ * tools.json), and registers `actions` on the executor for approved proposals.
+ *
+ * In a published setup you'd `import { definePlugin } from "@runravel/ravel"` for types;
+ * in-repo we export the plain definition (the loader validates it structurally).
+ */
+export default {
+  name: "notes",
+  version: "1.0.0",
+
+  tools: [
+    {
+      // Plain tool (policy `auto`): writes straight to team memory.
+      name: "note_append",
+      description: "Append a note to the team's shared notes list.",
+      schema: { text: z.string() },
+      handler: async (input: Record<string, unknown>, ctx: any) => {
+        const raw = await ctx.memory.get(ctx.teamScope, "notes");
+        const list = raw ? (JSON.parse(raw) as unknown[]) : [];
+        list.push({ text: String(input["text"]), at: new Date().toISOString() });
+        await ctx.memory.set(ctx.teamScope, "notes", JSON.stringify(list));
+        return { ok: true, count: list.length };
+      },
+    },
+    {
+      // Gated tool (policy `ask`): the model-facing stub. The real write is the
+      // identically-named action below, run by the executor on human approval.
+      name: "publish_note",
+      description: "Propose publishing a note externally (requires human approval).",
+      schema: { text: z.string() },
+      handler: async (input: Record<string, unknown>) => ({ proposed: `publish: ${String(input["text"])}` }),
+    },
+  ],
+
+  actions: [
+    {
+      name: "publish_note",
+      handler: async (input: unknown, ctx: any) => {
+        if (!ctx.teamScope) return { ok: false, error: "no team scope on proposal" };
+        const text = String((input as Record<string, unknown>)?.["text"] ?? "");
+        const raw = await ctx.memory.get(ctx.teamScope, "published");
+        const list = raw ? (JSON.parse(raw) as unknown[]) : [];
+        list.push({ text, at: new Date().toISOString() });
+        await ctx.memory.set(ctx.teamScope, "published", JSON.stringify(list));
+        return { ok: true, result: `published "${text}"` };
+      },
+    },
+  ],
+};

package/examples/plugin-demo/scribe/tools.json

@@ -0,0 +1,9 @@
+{
+  "defaultPolicy": "ask",
+  "builtins": "none",
+  "tools": [
+    { "name": "note_append", "policy": "auto", "description": "Append a note to the team's shared notes (plugin tool)." },
+    { "name": "publish_note", "policy": "ask", "description": "Propose publishing a note externally — requires human approval (plugin gated tool)." }
+  ],
+  "mcpServers": {}
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@runravel/ravel",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Ravel — an agentic runtime: define an agentic team as a folder of agents, tools, and processes, and run it with orchestration, budgets, scheduling, and human-in-the-loop approval.",
+  "license": "Apache-2.0",
+  "author": "Oren Yagev",
+  "homepage": "https://runravel.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RunRavel/ravel.git"
+  },
+  "bugs": {
+    "url": "https://github.com/RunRavel/ravel/issues"
+  },
+  "keywords": [
+    "agents",
+    "ai",
+    "agentic",
+    "runtime",
+    "orchestration",
+    "claude",
+    "mcp",
+    "human-in-the-loop"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "ravel": "./bin/ravel.mjs"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "bin",
+    "examples",
+    "!**/.ravel",
+    "!**/.businessos",
+    "!**/.env",
+    "ui/dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "ravel": "tsx src/cli/main.ts",
+    "prepublishOnly": "cd ui && npm ci && npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.1.0",
+    "chokidar": "^4.0.3",
+    "tsx": "^4.19.2",
+    "yaml": "^2.7.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.0"
+  }
+}