@openora/create 0.1.0

package/template/__dot__rulesync/commands/start.md

@@ -0,0 +1,11 @@
+---
+targets:
+  - '*'
+description: First-run onboarding for this consumer igaming repo. Interview the user for requirements, then delegate the build to the scoped agents. Invokes the `start` MCP tool.
+---
+
+Call the `start` MCP tool (server `oss`) with no arguments, then follow the script it returns exactly. If the user already described what they want to build, pass it as the `ask` argument.
+
+The returned script will have you: confirm the MCP server is connected, run a thorough requirements interview, call `enhance-intent`, then delegate the implementation to the `expert`, `builder`, and `qa` agents (via the Task tool). You gather requirements and orchestrate; you do not write feature code yourself, and you never modify `@openora/*` core.
+
+If the `start` tool is not available, the `oss` MCP server is not connected - tell the user to run `pnpm setup:mcp` and restart the editor.

package/template/__dot__rulesync/hooks/_shared.mjs

@@ -0,0 +1,60 @@
+// Shared helpers for the cross-CLI hook guards.
+//
+// One script serves Claude Code, Copilot CLI, Codex CLI, and Gemini CLI. Each
+// passes the tool call as JSON on stdin but with a slightly different shape:
+//   Claude / Codex : { tool_name, tool_input: { command?, file_path? } }
+//   Copilot        : { toolName,  toolArgs: "<json-string>" | object }
+//   Gemini         : { toolName/tool_name, ... } (best-effort)
+//
+// Deny is universal: exit code 2 + a message on stderr. Every other path exits 0
+// (allow). We FAIL OPEN on any parse error or uncertainty - Copilot's preToolUse
+// is fail-closed, so a crashing/slow guard would block real work; we never do
+// that, we only block on a positive match.
+
+import { readFileSync } from 'node:fs';
+
+export function readPayload() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8') || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function toolArgsObject(payload) {
+  const a = payload.toolArgs;
+  if (typeof a === 'string') {
+    try {
+      return JSON.parse(a);
+    } catch {
+      return {};
+    }
+  }
+  return a && typeof a === 'object' ? a : {};
+}
+
+export function extractCommand(payload) {
+  const ti = payload.tool_input ?? {};
+  const ca = toolArgsObject(payload);
+  return String(ti.command ?? ca.command ?? '');
+}
+
+export function extractFilePath(payload) {
+  const ti = payload.tool_input ?? {};
+  const ca = toolArgsObject(payload);
+  return String(
+    ti.file_path ??
+      ti.path ??
+      ca.path ??
+      ca.filePath ??
+      ca.file ??
+      ca.targetFile ??
+      ca.target_file ??
+      '',
+  );
+}
+
+export function deny(message) {
+  process.stderr.write(message.endsWith('\n') ? message : message + '\n');
+  process.exit(2);
+}

package/template/__dot__rulesync/hooks/guard-core.mjs.tpl

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// PreToolUse guard (Claude / Copilot CLI / Codex CLI / Gemini CLI).
+// Enforces the HARD RULE: never modify OSS core. Blocks shell write-primitives
+// and direct file edits that target the linked OSS checkout or node_modules.
+// Reads/blocks are allowed; only writes into protected paths are denied.
+
+import { extractCommand, extractFilePath, readPayload, deny } from './_shared.mjs';
+
+const payload = readPayload();
+
+// The linked OSS core checkout (baked in at generation time) plus any node_modules.
+const ossPath = String.raw`{{ossFromRoot}}`;
+const escapedOss = ossPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const PROTECTED = `(?:${escapedOss}|node_modules\\b)`;
+
+// 1) Shell command writing into a protected path (sed -i, redirect, tee, rm, ...).
+const command = extractCommand(payload);
+if (command) {
+  const writeToCore = [
+    [new RegExp(String.raw`\b(?:sed|perl)\b[^|;&]*\s-\w*i\w*\b[^|;&]*(?:${PROTECTED})`), 'in-place edit (sed/perl -i)'],
+    [new RegExp(String.raw`(?:>>?|>\|)\s*['"]?[^'"\s|;&]*(?:${PROTECTED})`), 'shell redirection'],
+    [new RegExp(String.raw`\btee\b\s+(?:-a\s+)?['"]?[^'"\s|;&]*(?:${PROTECTED})`), 'tee'],
+    [new RegExp(String.raw`\b(?:rm|truncate|dd|chmod|chown|unlink|shred|mv)\b[^|;&]*(?:${PROTECTED})`), 'destructive file op'],
+  ];
+  const hit = writeToCore.find(([re]) => re.test(command));
+  if (hit) {
+    deny(
+      `Blocked: this ${hit[1]} writes into OSS core / node_modules, which is read-only here. ` +
+        'Extend the platform from the OUTSIDE (overlay plugin, adapter rebinding, UI plugin, config). ' +
+        'If it can only be fixed in core, STOP and report it as an upstream OSS issue.',
+    );
+  }
+}
+
+// 2) Direct file edit/write whose target is inside a protected path.
+const filePath = extractFilePath(payload);
+if (filePath && new RegExp(PROTECTED).test(filePath)) {
+  deny(
+    `Blocked: ${filePath} is inside OSS core / node_modules, which is read-only here. ` +
+      'Extend from the OUTSIDE (overlay, adapter, UI plugin, config), or report an upstream OSS issue.',
+  );
+}
+
+process.exit(0);

package/template/__dot__rulesync/hooks/guard-generated.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// PreToolUse guard (Claude / Copilot CLI / Codex CLI).
+// Blocks edits to files generated by rulesync (`pnpm sync:agents`). The single
+// source of truth is .rulesync/; editing a generated mirror is lost on the next
+// sync. Fail-open: only a positive match denies.
+
+import { extractFilePath, readPayload, deny } from './_shared.mjs';
+import { relative, isAbsolute } from 'node:path';
+
+const payload = readPayload();
+const filePath = extractFilePath(payload);
+if (!filePath) process.exit(0);
+
+const rel = isAbsolute(filePath) ? relative(process.cwd(), filePath) : filePath;
+
+const generated = [
+  /^AGENTS\.md$/,
+  /^CLAUDE\.md$/,
+  /^\.github\/copilot-instructions\.md$/,
+  /^\.mcp\.json$/,
+  /^\.vscode\/mcp\.json$/,
+  /^\.codex\/config\.toml$/,
+  /^\.claude\/(agents|commands)\//,
+  /^\.github\/(agents|prompts)\//,
+];
+
+if (generated.some((re) => re.test(rel))) {
+  deny(
+    `Blocked: ${rel} is generated by rulesync (\`pnpm sync:agents\`). ` +
+      'Edit the source under .rulesync/ instead (rules/, subagents/, commands/, mcp.json), then run `pnpm sync:agents`.',
+  );
+}
+
+process.exit(0);

package/template/__dot__rulesync/hooks/guard-subagent.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// PreToolUse(Task) guard: keep the orchestrator from spawning a GENERIC subagent
+// (general-purpose / claude) for work a roster agent is purpose-built for. The
+// Agent roster in AGENTS.md is prose the model sometimes skips out of habit; this
+// is the deterministic backstop.
+//
+// Conservative by design: it acts ONLY when (a) the chosen subagent is generic AND
+// (b) the task text contains a HIGH-SIGNAL phrase that maps unambiguously to one
+// roster agent. Generic verbs ("implement", "test", "review") are deliberately not
+// triggers. Fail-open on anything unexpected (a crashing guard must never wedge work).
+
+import { readPayload } from './_shared.mjs';
+
+const payload = readPayload();
+const ti = payload.tool_input ?? {};
+const sub = String(ti.subagent_type ?? '').toLowerCase();
+
+const GENERIC = new Set(['general-purpose', 'claude', '']);
+if (!GENERIC.has(sub)) process.exit(0);
+
+const text = `${ti.description ?? ''}\n${ti.prompt ?? ''}`.toLowerCase();
+
+// High-signal phrase -> the roster agent that owns it. Keep each pattern SPECIFIC;
+// err toward missing a case over false-blocking a generic task.
+const ROUTES = [
+  { agent: 'qa', re: /\b(playwright|e2e test|end-to-end test|e2e coverage)\b/ },
+  {
+    agent: 'debugger',
+    re: /\b(build (failure|error)|turbopack|tsc error|module resolution|runtime error|stack trace)\b/,
+  },
+  {
+    agent: 'expert',
+    re: /\b(acceptance criteria|responsible gaming|regulatory requirement|jurisdiction)\b/,
+  },
+  {
+    agent: 'builder',
+    re: /\b(overlay plugin|adapter swap|swap (the )?(kyc|psp|payment|notification)|extensions?\.config|mount (a |the )?page)\b/,
+  },
+  {
+    agent: 'deployer',
+    re: /\b(dockerfile|containerize|deploy pipeline|deploy to (ecs|kubernetes|fly|railway|render)|ci\/cd deploy|helm chart)\b/,
+  },
+];
+
+const hit = ROUTES.find((r) => r.re.test(text));
+if (!hit) process.exit(0);
+
+process.stderr.write(
+  `Use the \`${hit.agent}\` subagent for this task, not \`${sub || 'general-purpose'}\`. ` +
+    `It is pre-scoped for this work (tools + model + brief) - see the Agent roster in AGENTS.md. ` +
+    `Re-issue the Task with subagent_type: "${hit.agent}". ` +
+    `If it genuinely does not fit ${hit.agent}, rephrase the description to say why.\n`,
+);
+process.exit(2);

package/template/__dot__rulesync/hooks/post-edit.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join, isAbsolute, relative } from 'node:path';
+import { extractFilePath, readPayload } from './_shared.mjs';
+
+const CAP_LINES = 40;
+const CAP_CHARS = 2000;
+
+const filePath = extractFilePath(readPayload());
+if (!filePath) process.exit(0);
+if (!/\.(ts|tsx)$/.test(filePath) || /\.d\.ts$/.test(filePath)) process.exit(0);
+if (filePath.includes('/templates/') || filePath.includes('/generated/')) process.exit(0);
+
+// Lint-fix (best effort - never block on the linter).
+try {
+  execSync(`pnpm exec oxlint --fix "${filePath}"`, { stdio: 'pipe' });
+} catch {
+  /* oxlint unavailable or errored - fall through to typecheck */
+}
+
+function packageNameFor(fp) {
+  const m = fp.match(/(.*?\/(?:apps\/[^/]+|packages\/[^/]+\/[^/]+))\//);
+  if (!m) return null;
+  try {
+    const pkg = JSON.parse(readFileSync(join(m[1], 'package.json'), 'utf8'));
+    if (!pkg.name || !pkg.scripts?.typecheck) return null;
+    return pkg.name;
+  } catch {
+    return null;
+  }
+}
+
+const abs = isAbsolute(filePath) ? filePath : join(process.cwd(), filePath);
+const owner = packageNameFor(abs);
+if (!owner) process.exit(0);
+
+function cap(text) {
+  const out = text.split('\n').slice(0, CAP_LINES).join('\n').slice(0, CAP_CHARS);
+  return out.length < text.length ? `${out}\n... (truncated)` : out;
+}
+
+try {
+  execSync(`pnpm --filter "${owner}" typecheck`, { stdio: 'pipe' });
+  process.exit(0);
+} catch (e) {
+  const output = (e.stdout?.toString() ?? '') + (e.stderr?.toString() ?? '');
+  const basename =
+    (isAbsolute(filePath) ? relative(process.cwd(), filePath) : filePath).split('/').pop() ?? '';
+  if (basename && output.includes(basename)) {
+    process.stderr.write(
+      `Typecheck failed for ${owner} after editing ${basename}:\n${cap(output)}`,
+    );
+    process.exit(2);
+  }
+  process.exit(0);
+}

package/template/__dot__rulesync/hooks.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      { "type": "command", "command": "node .rulesync/hooks/guard-core.mjs" },
+      { "type": "command", "command": "node .rulesync/hooks/guard-generated.mjs" },
+      { "type": "command", "matcher": "Task", "command": "node .rulesync/hooks/guard-subagent.mjs" }
+    ],
+    "postToolUse": [{ "type": "command", "command": "node .rulesync/hooks/post-edit.mjs" }]
+  }
+}

package/template/__dot__rulesync/mcp.json.tpl

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/mcp-schema.json",
+  "mcpServers": {
+    "oss": {
+      "type": "stdio",
+      "command": "{{mcpCommand}}",
+      "args": {{mcpArgsJson}}
+    }
+  }
+}

package/template/__dot__rulesync/rules/db-conventions.md

@@ -0,0 +1,83 @@
+---
+root: false
+targets:
+  - '*'
+globs:
+  - 'apps/api/**'
+description: SQL / Drizzle conventions for tables an overlay or local add-on owns.
+---
+
+# Database conventions (SQL / Drizzle)
+
+Applies to every table an overlay or local add-on owns (`apps/api/src/extensions/<name>/src/schema/`).
+Tables live in `@openora/*` core for platform domains - never edit those; these rules govern the
+tables you add. Boundary/import rules live in `oss-boundaries`; this file is SQL only.
+
+## Identifiers - snake_case everywhere
+
+Every drizzle instance sets `casing: 'snake_case'`, so the SQL name derives from the camelCase key.
+Pass an explicit name only where casing can't derive it: table names, `pgEnum` types, index names.
+
+```ts
+// good - key derives the column; const camelCase; explicit snake_case only for table + index
+export const playerNote = pgTable(
+  'player_note',
+  {
+    id: uuid().primaryKey().defaultRandom(),
+    playerId: uuid().notNull(), // -> player_id
+    createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [index('player_note_player_id_idx').on(t.playerId)],
+);
+
+// bad - explicit/camelCase column names, PascalCase table
+pgTable('PlayerNote', { player_id: uuid('playerId') });
+```
+
+## Timestamps - always timestamptz
+
+```ts
+createdAt: timestamp({ withTimezone: true }); // good - Postgres timestamptz, store UTC
+createdAt: timestamp(); // bad - naive, drops the zone
+```
+
+Every datetime column (`createdAt`, `updatedAt`, `expiresAt`, any `*At`) carries the zone.
+
+## Keys, references, indexes
+
+- UUID primary keys (`uuid().primaryKey().defaultRandom()`).
+- **No foreign keys across a module/overlay boundary** - store a plain ID string and resolve via the
+  oRPC client or a schema subpath. FKs only within the same add-on.
+- `NOT NULL` by default; push defaults to the DB (`.notNull().default(...)`), not app code.
+- Index every column you filter or join on; name it `<table>_<cols>_idx`.
+
+## Efficient operations
+
+```ts
+// bad - N+1
+for (const id of ids) await db.select().from(wallet).where(eq(wallet.playerId, id));
+// good - one batched query
+await db.select().from(wallet).where(inArray(wallet.playerId, ids));
+```
+
+- Select only the columns you use; don't `select(*)` wide rows to read one field.
+- **Build rows by spread + override, never hand-copy field-by-field.** When a row mostly mirrors a
+  validated input, spread it and set only the server-computed fields - `db.insert(x).values({ ...input,
+id, createdAt })` - never re-list `field: input.field` per key (it silently drifts the moment a
+  column is added). Keep fields explicit only for: an order-sensitive hash/signature payload; a source
+  carrying columns the row must not receive (spread then omit them); or a null-vs-undefined boundary
+  that won't coerce (`actorId: input.actorId ?? null`).
+- **Money / critical paths are transactional and idempotent** - a DB guard inside the transaction,
+  not just an `idempotencyKey` (delivery is at-least-once).
+
+```ts
+await db.transaction(async (t) => {
+  if (await ledgerExists(t, idempotencyKey)) return; // guard, not just a key
+  await insertLedger(t, { idempotencyKey, amountCents });
+});
+```
+
+## Migrations
+
+- Never hand-edit generated migrations. Change the `pgTable`, then `pnpm db:migrate`.
+- One migration per schema change; review the generated SQL before committing.

package/template/__dot__rulesync/rules/overview.md

@@ -0,0 +1,92 @@
+---
+root: true
+targets:
+  - '*'
+globs:
+  - '**/*'
+---
+
+# Agent instructions
+
+Canonical brief for AI agents (Claude Code, GitHub Copilot, Codex) and humans working on
+this repo. Every per-tool instruction file (`AGENTS.md` - shared, also Codex's brief;
+`CLAUDE.md`; `.github/copilot-instructions.md`) plus Codex's `.codex/config.toml` and the
+subagent and command mirrors are generated by
+[rulesync](https://github.com/dyoshikawa/rulesync) from the single source in `.rulesync/`
+(`rules/`, `subagents/`, `commands/`, `mcp.json`). Edit the source under `.rulesync/`, then
+run `pnpm sync:agents`. Do not hand-edit the generated files.
+
+This repo is a downstream igaming operator built on the OSS platform (`@openora/*`).
+
+## HARD RULE: never modify OSS core
+
+`@openora/*` is a third-party dependency - treat it like any published npm package. You may READ it for reference, never write to it.
+
+- Do NOT edit anything in `node_modules/**` or in the linked OSS checkout. Edit/Write to those paths is denied in `.claude/settings.json`; do not try to work around it with `sed`, shell redirection, or a script.
+- Locally patching a dependency is an anti-pattern: it is lost on reinstall and diverges from the published package every other operator uses.
+- You extend the platform from the OUTSIDE only - overlay plugins, adapter rebindings, UI plugins, config. Never fork or hand-edit core.
+- If something can only be fixed in core, STOP and report it as an upstream bug/feature request for the OSS repo (describe the problem, expected behavior, where you think it lives). Do not patch it here.
+
+## Getting started
+
+When the user opens Claude Code or asks to build something, call the `start` MCP tool (server: `oss`) and follow the script it returns.
+
+Trigger phrases: "start", "help", "what can I build", "what can I do", "I want to build X", "how do I begin", "getting started".
+
+## Enhance the ask first (pre-step)
+
+Before acting on any non-trivial request - and before delegating to an agent - run the `enhance-prompt` skill on the raw ask: restate the intent, gather scoped context (your tracker / roadmap / team chat / local docs), surface the blocking ambiguities, and produce the brief you actually execute. Skip it only when the ask is already precise. Subagents act on the brief they are handed - they do not re-enhance it.
+
+## How you work here: collect requirements, delegate everything else
+
+Your one human-facing job is to **gather thorough requirements** from the user - interview them (goal, actors, value flow, rules, lifecycle, compliance, UI, edge cases, success criteria, out of scope) until you could hand a stranger a buildable spec. The `start` / `enhance-intent` tools give you the checklist.
+
+Once requirements are confirmed, **delegate the rest to the agents** via the Task tool - you orchestrate, you do not implement feature code yourself:
+
+1. `expert` - formalizes the requirements into acceptance criteria, flags compliance/gaps.
+2. `builder` - implements (`pnpm gen ...`, code, wiring).
+3. `qa` - writes/runs the E2E test against the acceptance criteria.
+
+Only return to the user to resolve genuine decisions they alone can make.
+
+## What this repo is
+
+- `apps/api/` - thin Hono + oRPC API entry, your own `extensions.config.ts`
+- this is a headless api consumer; build your frontend in its own repo and consume the api over HTTP via `@openora/react`
+- `@openora/*` packages are linked from a sibling OSS checkout via `pnpm.overrides`
+
+## How to extend
+
+| What you want                                | Command            |
+| -------------------------------------------- | ------------------ |
+| New behavior / routes                        | `pnpm gen plugin`  |
+| Swap a vendor (payment / KYC / notification) | `pnpm gen adapter` |
+
+Register new plugins in `apps/api/src/extensions.config.ts`. Adapters must be listed AFTER the module that owns the default binding (last registration of a DI token wins).
+
+## Agents (spawn via the Task tool)
+
+Delegate work to these scoped agents - the `start` / `enhance-intent` playbooks tell you when to use each:
+
+- `expert` - turns a fuzzy product ask into requirements + acceptance criteria (jurisdiction rules, player journey). Advisory, writes no code. Use BEFORE building anything non-obvious.
+- `builder` - senior fullstack engineer. Implements overlays, swaps adapters, mounts UI pages.
+- `qa` - writes/runs Playwright E2E tests; triages whether a bug is in OSS core (upstream) or your overlay (local fix).
+- `debugger` - root-causes failures, build-time (Next/Turbopack, tsc, module resolution) and runtime (Chrome DevTools: console/network/DOM). Spawn it whenever something errors or behaves wrong; it finds the cause and routes the fix.
+
+This repo consumes OSS core as linked packages - never edit `@openora/*` source. If a bug is in core, report it upstream; extend from the outside via plugins.
+
+## MCP tools available (server: `oss`)
+
+This server reads the platform CATALOG (not OSS source) - it tells you what exists so you extend without forking. Call these instead of grepping:
+
+- `start` - onboarding flow (call when the user asks what to build)
+- `enhance-intent` - turn a fuzzy ask into a grounded spec + playbook
+- `dev:infra` - start/stop/status docker compose (postgres :5432)
+- `catalog-overview` - START HERE: counts + adapter seams + config fields
+- `list-adapters` - vendor swap seams (interface + token + status)
+- `list-routes [module]` - oRPC route namespaces
+- `list-events` - cross-module domain events you can subscribe to
+- `list-slots` - named UI slots you can fill from a UI plugin
+- `describe-module <name>` - one module's group, tables, routes
+- `schema-get <name>` - locate a Zod contract schema's file
+- `get-config-schema` - the igaming-config fields a consumer can set

package/template/__dot__rulesync/skills/add-feature/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: add-feature
+
+description: >
+  Deliver a feature end-to-end in this consumer repo. Aggregates context (Jira + Confluence + Slack +
+  Google Drive + Notion + local docs + past sessions + codebase), produces an approved plan, then drives
+  delivery by calling sibling skills - create-plugin (build), code-review (review), create-pr (MR) -
+  and create-task for ticket hygiene. Transitions Jira (no comments) and drafts a one-line Slack
+  notice. Use on "add feature", "plan <KEY>-XXX", "deliver <KEY>-XXX", or /add-feature [<KEY>-XXX].
+  Read-only until the plan is approved; never pushes, transitions Jira, or sends Slack without OK.
+---
+
+# add-feature
+
+Feature-delivery orchestrator for this consumer repo: one Jira key in, a delivered MR +
+updated ticket + drafted Slack notice out. You orchestrate and call sibling skills - you do not
+re-implement their work. The platform-core twin is the `/add-feature` skill in the platform OSS repo.
+
+## Coordinates
+
+- Jira: the **Atlassian** MCP, cloudId `<your-jira-cloud-id>`,
+  project `<your-project-key>` (ticket keys look like `<KEY>-XXX`). Pass `contentFormat` +
+  `responseContentFormat: "markdown"`.
+- GitLab: `<your-gitlab-project>`, MR target `dev`, `glab` CLI.
+- Slack: `<your-team-channel>`, draft only.
+- Repo: `apps/api` (Hono entry + extensions) consumes `@openora/*` upstream. This is a headless
+  API consumer; build your frontend in its own repo and consume the API over HTTP.
+- **Hard rule:** the linked OSS checkout is read-only (guard-core hook + permission deny). Extend from
+  the outside; core changes hand off - see `handoff.md`.
+
+## The contract
+
+- **Read-only until the Step 3 plan is approved.** No edits, commits, pushes, Jira writes, or Slack
+  sends before sign-off.
+- Reuse sibling skills, don't reinvent: **create-task** (ticket format), **create-plugin** (build an
+  overlay), **code-review** (review), **create-pr** (MR). Delegate code to subagents.
+
+## Steps
+
+### 1. Resolve input + enhance the ask
+
+`<KEY>-XXX` from `$ARGUMENTS`; if absent, ask. Echo it back. Run the `enhance-prompt` pre-step on the ask before gathering context, so Step 2 pulls only what's relevant and Step 3 plans against a clear brief.
+
+### 2. Gather context in parallel (read-only)
+
+Run together; skip any source that returns nothing. Read `handoff.md` only on core-change signals.
+
+| Source        | How                                                                                             |
+| ------------- | ----------------------------------------------------------------------------------------------- |
+| Jira          | the **Atlassian** MCP - read `<KEY>-XXX`: description, AC, comments, parent epic, linked issues |
+| Confluence    | the **Atlassian** (Confluence) MCP - search the space + read pages                              |
+| Slack         | the **Slack** MCP - search public/private, read threads, read canvases                          |
+| Google Drive  | the **Google Drive** MCP - PRDs, specs                                                          |
+| Notion        | `ntn` CLI per `notion-memory` skill - prior decisions, lessons                                  |
+| Local docs    | the OSS checkout's `docs` (ADRs, `architecture.md`, `catalog.json`), repo READMEs, `CLAUDE.md`  |
+| Past sessions | grep `~/.claude/projects/**` and `~/.claude/plans` for the ticket key                           |
+| Codebase      | `oss` MCP (read-only) + Explore - map touchpoints in `apps/api`                                 |
+
+### 3. Plan + classify (the gate)
+
+Synthesize into a plan and present it. Do NOT edit yet.
+
+- **Goal** (1-2 lines) + **Acceptance criteria** (observable, testable).
+- **Decisions found** - each with source (who/where/date), so they aren't relitigated.
+- **Open questions** - ask before proceeding if any blocks design.
+- **Implementation breakdown** - tasks mapped to files/packages + the owning subagent. Classify each:
+  - **downstream** -> overlay plugin / adapter swap / UI provider / config (build via `create-plugin`).
+  - **OSS-core** -> only fixable in `@openora/*`. Flag it; triggers `handoff.md`.
+- **Risks / dependencies** - external services, OSS handoff, data/migrations.
+
+Require explicit approval. Treat as plan mode even if the harness isn't.
+
+### 4. Build (delegate)
+
+After approval, for **downstream** work: run the **create-plugin** skill for each overlay/adapter/
+page slice - it scaffolds, wires `extensions.config.ts`, and enforces boundaries + audit + db rules.
+The owning subagent (`builder`) also writes unit + integration tests as part of the deliverable.
+`deployer` only if infra changes; `debugger` on demand for build/runtime failures.
+
+For **OSS-core** items: read `handoff.md`, write the work-order, STOP that slice, continue the rest.
+When implementation starts, transition Jira to In Progress (Step 7 - confirm first).
+
+### 5. Review + tests
+
+- Run **code-review** on the change set; loop `[BLOCK]`/`[WARN]` fixes back through `builder`.
+- Run `/check` (typecheck + lint). Don't proceed on red.
+- Derive an e2e checklist from the AC (happy path, edge cases, authz negatives, error states), then
+  `qa`: write/run the E2E specs, drive `chrome-devtools` on failure.
+
+### 6. Open the MR
+
+Run **create-pr**: it commits (`feat(<KEY>-XXX): ...`), reports the SHA, asks for "yes push", pushes,
+and `glab mr create`s targeting `dev` with the CODEOWNERS for the changed paths as reviewers. Don't
+bypass its push-consent gate.
+
+### 7. Jira status transition (NOT comments)
+
+Use the **Atlassian** MCP - fetch the transitions -> show current status + options -> **confirm** ->
+apply the matching one (In Progress when build starts, In Review when the MR opens). **No MR-link or status comments.**
+
+### 8. Draft Slack notice (one line)
+
+Use the **Slack** MCP to draft a message to `<your-team-channel>`: a single line - emoji + PR/task name
+as a link (e.g. `👉 <feature> - MR !NN`). **Draft only**, never direct-send.
+
+## Rules
+
+- Read-only until the Step 3 plan is approved.
+- Never push without an explicit per-action "yes push" (inherited from `create-pr`).
+- Never transition Jira without confirming; show status + options first. No Jira comments.
+- Slack is a one-line draft, never direct-send.
+- Never edit the linked OSS checkout; hand off via `handoff.md`. Prefer overlay/plugin/adapter/config.
+- One MR = one concern. Split unrelated work.

package/template/__dot__rulesync/skills/add-feature/handoff.md

@@ -0,0 +1,58 @@
+# OSS core handoff
+
+When an `add-feature` work item can only be fixed in `@openora/*` core, this consumer repo cannot
+edit it (the `guard-core.mjs` hook and `permissions.deny` block the linked OSS checkout). Hand off to
+the platform-core twin skill instead of fighting the guard.
+
+## When to hand off
+
+- The fix requires changing a contract, schema, service, router, or platform seam in `@openora/*`.
+- An overlay plugin / adapter swap / UI provider override / config change genuinely cannot
+  express the behavior.
+- Default bias: try to extend from the outside first. Only hand off when you've confirmed the
+  outside-in path doesn't exist.
+
+If you're unsure, say so in the plan (Step 3) and let the user decide before writing the order.
+
+## Work-order template
+
+Write to `~/.claude/plans/<ticket-key>-oss.md` so both repos and future sessions can read it:
+
+```markdown
+# OSS work order - <ticket-key>: <title>
+
+## Goal
+
+<what core must do, 1-2 lines>
+
+## Unblocks
+
+consumer feature <ticket-key> - <which downstream slice depends on this>
+
+## Core surface to change
+
+- <package / module / contract / adapter token, as specific as possible>
+
+## Contract / schema impact
+
+- <new or changed oRPC contracts, Drizzle tables, events; or "none">
+
+## Acceptance
+
+- <observable outcomes that prove the core change is correct>
+
+## Dependency
+
+consumer MR <url-or-TBD> stays in draft until this merges and a new @openora/core/\* version is consumed.
+```
+
+## Protocol
+
+1. The consumer repo writes the work-order and **stops** that slice (keep delivering independent
+   downstream slices meanwhile).
+2. The user runs `/add-feature` inside the platform OSS repo (separate cwd/session). It reads
+   the work-order, implements, and opens its own MR there.
+3. The consumer MR stays draft/blocked until the OSS MR merges and the consumer bumps the consumed
+   `@openora/*` version. Link the two by the work-order path and the ticket key.
+4. Note the handoff in the Jira ticket and the consumer MR description so the dependency is
+   visible.