kataster 0.0.0-stage → 0.2.1

package/.opencode/agents/requirements-engineer.md

@@ -0,0 +1,58 @@
+---
+description: Derives user stories with Gherkin acceptance criteria from docs/domain/events.yaml and the data model, and revises stories after reviews. Use after event storming or domain modeling.
+mode: subagent
+color: blue
+permissions:
+  - action: edit
+    resource: "*"
+    effect: deny
+  - action: edit
+    resource: docs/stories/*
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: deny
+  - action: webfetch
+    resource: "*"
+    effect: deny
+  - action: websearch
+    resource: "*"
+    effect: deny
+  - action: skill
+    resource: "*"
+    effect: deny
+  - action: skill
+    resource: user-stories
+    effect: allow
+---
+
+Before you start, load the skill `user-stories` with the `skill` tool.
+
+You are the requirements engineer for this project. You have NO context from the main conversation. Write in the artifact language (`languages.artifacts` in `.claude/project.json`, default English).
+
+## Sources of Truth (read before every task)
+- `docs/product/vision.md` – user groups and scope
+- `CONTEXT.md` – glossary; use the terms exactly as written, never an `_Avoid_` synonym
+- `docs/domain/events.yaml` – events, commands, actors, policies, read models, contexts. A command's `rules` are
+  **not** the whole truth: an invariant is stated once, on its `aggregate` (user, 2026-10-01), so always read the
+  aggregate's `invariants` too and derive a rejection scenario for every one the command can violate.
+- `docs/architecture/data-model.md` – if present
+- `docs/reviews/` – for revision tasks
+
+## Approach
+- Method, format, splitting patterns and numbering: see the preloaded skill `user-stories`.
+- Next free ID: check existing `docs/stories/ST-*.md` via Glob.
+- New stories get `status: draft`; once you're done with a story, `status: review`.
+- `priority` initially `should` (the PO decides), leave `size` empty (lead-dev estimates).
+- Never edit `docs/stories/BACKLOG.md`; it is regenerated automatically from the story files.
+- With a tracker (`backlog.provider` ≠ `local`), write the local mirror only. Never set `external` by hand and never
+  call Jira/GitHub yourself – the main session pushes with `/backlog-sync push` after you are done.
+
+## Validation
+After every write, a hook checks the file automatically. If it reports errors, fix them immediately in the same file. Never work around rules (e.g. padding scenarios just to reach the minimum count).
+
+## Uncertainties
+Don't guess. Mark open points in the story with `[OPEN]` AND collect them with the story ID in `docs/stories/OPEN_QUESTIONS.md`. Don't invent missing domain terms or events – report them as open questions.
+
+## Output (reply to the main session)
+List of created/changed stories (ID, title, context, linked events), coverage: which commands don't have a story yet, open questions.

package/.opencode/agents/ux-designer.md

@@ -0,0 +1,83 @@
+---
+description: UX/UI designer. Reviews stories with a frontend part and existing screens against docs/product/ux-guidelines.md, and maintains those guidelines. Use in backlog grooming for stories labelled `ui`, and when a feature's grilling changed a UX guideline.
+mode: subagent
+color: pink
+permissions:
+  - action: edit
+    resource: "*"
+    effect: deny
+  - action: edit
+    resource: docs/product/ux-guidelines.md
+    effect: allow
+  - action: edit
+    resource: docs/reviews/*
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: deny
+  - action: webfetch
+    resource: "*"
+    effect: deny
+  - action: websearch
+    resource: "*"
+    effect: deny
+  - action: skill
+    resource: "*"
+    effect: deny
+  - action: skill
+    resource: ux-design
+    effect: allow
+  - action: skill
+    resource: user-stories
+    effect: allow
+---
+
+Before you start, load the skills `ux-design` and `user-stories` with the `skill` tool.
+
+You are the UX/UI designer of this project, whose interface its users meet in the situations
+`docs/product/vision.md` describes. You have NO context from the main conversation – everything relevant is in `docs/` and in the code.
+Write in the artifact language (`languages.artifacts` in `.claude/project.json`, default English); the UI texts you propose are in the project UI language (`languages.ui` in `.claude/project.json`).
+
+## Yardstick
+- `docs/product/ux-guidelines.md` – the decisions already made. **Your file.** If it does not exist yet, say so
+  and propose its first content instead of judging against rules nobody agreed to.
+- `docs/product/vision.md` – user groups, devices, constraints, non-goals
+- `CONTEXT.md` – the glossary; UI terms use the `_UI (<lang>)_` wording exactly
+- `docs/engineering/conventions.md` – the page frame, the design size, component rules, where the
+  message catalogs live. What is decided there is not yours to re-decide.
+- The method, the question set and the review order: the preloaded skill `ux-design`.
+
+## Tasks
+1. **Story review** – per story with a frontend part: is the screen's job clear, is the entry point named, do the
+   empty, rejected and no-permission cases have a scenario, is the UI wording decided and does it match the
+   glossary? Name what is missing as concrete scenarios or Context lines the requirements-engineer can apply.
+2. **Screen review** – read the page, the form and the message catalog in the code (`repo.codeRoots` in `.claude/project.json`), and judge in the order the
+   skill gives. Findings only; you never change application code.
+3. **Guidelines** – after the user approves a decision, write it into `docs/product/ux-guidelines.md` as a rule,
+   with the date and the reason. Keep it short enough that someone reads it before writing a page.
+4. **Gaps** – which recurring interface question has no guideline yet, and which existing screens contradict each
+   other?
+
+## Boundaries
+- **You never write stories.** Everything that belongs in a story comes back as a recommendation – the
+  `requirements-engineer` applies it. The same rule the product-owner and the lead-dev follow.
+- You never write application code, tests or the engineering conventions.
+- No implementation detail in what you propose: no component names, no classes, no pixel values. Observable
+  behaviour and words, not markup.
+- Make no assumptions where the vision or the guidelines are silent: return them as questions, each with a
+  recommended answer, as the `grilling` skill requires.
+- Don't invent domain terms. A term that is missing belongs in `CONTEXT.md` first, through the domain-model skill
+  – say so, don't use a synonym.
+- Never edit `docs/stories/BACKLOG.md`; it is generated.
+
+## Output (reply to the main session)
+A table of findings:
+
+| Story / screen | Level (job / understanding / states / language / consistency / polish) | Severity (blocker, major, minor) | Finding | What to do instead |
+
+Below it: the scenarios or Context lines you propose per story (ready for the requirements-engineer to apply), the
+guidelines you would add, and at most 3 questions for the user, each with a recommended answer.
+
+Severity means: **blocker** – the person cannot do the job, or cannot on a phone; **major** – they can, but will
+get it wrong, misread it or not find it; **minor** – it works and is understood, but is inconsistent or clumsy.
+Be honest about the difference; calling polish a blocker costs you the next argument.

package/.opencode/commands/adopt.md

@@ -0,0 +1,7 @@
+---
+description: Brownfield entry point – maps the repository, adopts it in slices (one domain plus at most one shared library), drafts the domain model with evidence, documents each package where it lives, then grills the user and records the gap; stories only with --stories.
+---
+
+Load the `adopt` skill with the `skill` tool and follow it exactly. Do not restate it.
+
+Arguments: $ARGUMENTS

package/.opencode/commands/backlog-sync.md

@@ -0,0 +1,7 @@
+---
+description: Syncs the local story mirror with the configured backlog backend – local (default), GitHub Issues, or Jira via MCP.
+---
+
+Load the `backlog` skill with the `skill` tool and follow it exactly. Do not restate it.
+
+Arguments: $ARGUMENTS

package/.opencode/commands/bootstrap.md

@@ -0,0 +1,7 @@
+---
+description: Greenfield entry point – grills the vision, runs a big-picture event storming, builds the domain model and architecture with ADRs, sets the UX yardstick and derives the foundation stories and first vertical slice.
+---
+
+Load the `bootstrap` skill with the `skill` tool and follow it exactly. Do not restate it.
+
+Arguments: $ARGUMENTS

package/.opencode/commands/event-storming.md

@@ -0,0 +1,7 @@
+---
+description: Facilitates an interactive event storming with the user (big picture or a single process) and maintains docs/domain/events.yaml and the glossary in CONTEXT.md.
+---
+
+Load the `event-storming` skill with the `skill` tool and follow it exactly. Do not restate it.
+
+Arguments: $ARGUMENTS

package/.opencode/commands/feature.md

@@ -0,0 +1,7 @@
+---
+description: Entry point for a new feature or change once the initial discovery is done – accepts a free-text idea, an existing story (`ST-NNN`) or a ticket (`#123`, `PROJ-123`, URL); grills the idea, runs a focused event storming, updates domain model and ADRs, derives stories into the backlog (local, or the tracker mirror) and runs the story review; bug tickets go to a regression story.
+---
+
+Load the `feature` skill with the `skill` tool and follow it exactly. Do not restate it.
+
+Arguments: $ARGUMENTS

package/.opencode/commands/grill-me.md

@@ -0,0 +1,7 @@
+---
+description: A relentless interview to sharpen a plan or design.
+---
+
+Load the `grill-me` skill with the `skill` tool and follow it exactly. Do not restate it.
+
+Arguments: $ARGUMENTS

package/.opencode/commands/grill-with-docs.md

@@ -0,0 +1,7 @@
+---
+description: A relentless interview to sharpen a plan or design, which also creates docs (glossary in CONTEXT.md and ADRs in docs/adr/) as we go.
+---
+
+Load the `grill-with-docs` skill with the `skill` tool and follow it exactly. Do not restate it.
+
+Arguments: $ARGUMENTS

package/.opencode/commands/groom-backlog.md

@@ -0,0 +1,7 @@
+---
+description: Periodic grooming of the open backlog – challenges whether stories are still worth building, whether dependencies still hold and whether the priorities still match what the product needs now.
+---
+
+Load the `groom-backlog` skill with the `skill` tool and follow it exactly. Do not restate it.
+
+Arguments: $ARGUMENTS

package/.opencode/commands/implement.md

@@ -0,0 +1,7 @@
+---
+description: Engineering workflow – implements one story from docs/stories/ test-first on its own branch, verifies, has it reviewed by code-reviewer and acceptance-tester, refactors, and sets it done on the acceptance tester's verdict and hands the pull request to the user to merge.
+---
+
+Load the `implement` skill with the `skill` tool and follow it exactly. Do not restate it.
+
+Arguments: $ARGUMENTS

package/.opencode/commands/improve-codebase-architecture.md

@@ -0,0 +1,7 @@
+---
+description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
+---
+
+Load the `improve-codebase-architecture` skill with the `skill` tool and follow it exactly. Do not restate it.
+
+Arguments: $ARGUMENTS

package/.opencode/commands/retro.md

@@ -0,0 +1,7 @@
+---
+description: Conduct a retrospective on a coding session.
+---
+
+Load the `retro` skill with the `skill` tool and follow it exactly. Do not restate it.
+
+Arguments: $ARGUMENTS

package/.opencode/commands/review-stories.md

@@ -0,0 +1,7 @@
+---
+description: Has stories checked in one lead-dev pass (value, build, UX), applies the small fixes and guides the user to approval (status ready).
+---
+
+Load the `review-stories` skill with the `skill` tool and follow it exactly. Do not restate it.
+
+Arguments: $ARGUMENTS

package/.opencode/commands/shape.md

@@ -0,0 +1,7 @@
+---
+description: Grill a large idea before it becomes features – frame the problem, decide where it belongs (existing or new bounded context, shared library), map what changes vs. what is new, slice it, and produce a rough cost range with confidence. Creates no stories; ends with a go / slice / spike / discover / park / no-go recommendation.
+---
+
+Load the `shape` skill with the `skill` tool and follow it exactly. Do not restate it.
+
+Arguments: $ARGUMENTS

package/.opencode/opencode.jsonc

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+
+  // The workflow itself lives in .claude/ and is shared with Claude Code.
+  // .opencode/ holds the OpenCode wiring: agents, commands, the hook adapter plugin.
+  //
+  // Permissions: the hard blocks (force push, production deploy, destructive database
+  // commands, generated files, accepted ADRs) are enforced by
+  // .opencode/plugins/kataster/index.ts, which runs the .claude/hooks/*.ts scripts.
+  // Per-agent write scopes are expressed as `edit` permissions in .opencode/agents/*.md.
+
+  "watcher": {
+    "ignore": ["**/node_modules/**", "**/.next/**", "**/dist/**", "**/coverage/**"]
+  }
+}

package/.opencode/plugins/kataster/index.ts

@@ -0,0 +1,283 @@
+/**
+ * OpenCode adapter for the Kataster workflow.
+ *
+ * The actual logic lives in `.claude/hooks/*.ts` (plain Node, shared with Claude Code).
+ * This plugin only translates OpenCode's hook events into the JSON those scripts read
+ * on stdin and their exit codes back into OpenCode behaviour:
+ *
+ *   SessionStart   -> event `session.created`          -> instructions entry
+ *   PreToolUse     -> tool hook `execute.before`        -> throw = block
+ *   PostToolUse    -> tool hook `execute.after`         -> append text to the result
+ *   Stop           -> session hook `experimental.idle`  -> synthetic message once
+ *
+ * OpenCode also has no path-scoped rules: on every read or write, matching `.claude/rules/*.md` files are
+ * attached as keyed instruction entries (`path-rules.ts`), so both harnesses see the same rules.
+ *
+ * The per-agent path guard is not wired here: it is expressed as `edit` permissions in
+ * `.opencode/agents/*.md`, which is the native OpenCode equivalent.
+ */
+import { Plugin } from "@opencode/plugin";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+
+type HookResult = { code: number; stdout: string; stderr: string };
+
+/** Claude tool names the hook scripts switch on. */
+const TOOL_NAME: Record<string, string> = {
+  write: "Write",
+  edit: "Edit",
+  patch: "MultiEdit",
+  shell: "Bash",
+};
+
+function pick(input: unknown, ...names: string[]): unknown {
+  const obj = input as Record<string, unknown> | undefined;
+  for (const name of names) if (obj?.[name] !== undefined) return obj[name];
+  return undefined;
+}
+
+/** Map an OpenCode tool input onto the `tool_input` shape the Claude hooks expect. */
+function claudeInput(tool: string, input: unknown): Record<string, unknown> {
+  if (tool === "shell") return { command: pick(input, "command") ?? "" };
+
+  const file_path = pick(input, "filePath", "file_path", "path", "file");
+  if (tool === "write") return { file_path, content: pick(input, "content") };
+  if (tool === "edit")
+    return {
+      file_path,
+      old_string: pick(input, "oldString", "old_string"),
+      new_string: pick(input, "newString", "new_string"),
+      replace_all: pick(input, "replaceAll", "replace_all"),
+    };
+  // `patch` carries no old/new strings; the path alone is enough for the guards.
+  return { file_path };
+}
+
+function additionalContext(stdout: string): string | undefined {
+  try {
+    return JSON.parse(stdout)?.hookSpecificOutput?.additionalContext;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Files a tool call touches. `patch` carries a patch text instead of one path. */
+function toolPaths(tool: string, input: unknown): string[] {
+  if (tool === "patch") {
+    const text = String(pick(input, "patchText", "patch_text", "patch") ?? "");
+    const out: string[] = [];
+    for (const line of text.split("\n")) {
+      const match = /^\*\*\* (?:Add|Update|Delete) File: (.+)$/.exec(line) ?? /^\*\*\* Move to: (.+)$/.exec(line);
+      if (match) out.push(match[1].trim());
+    }
+    return [...new Set(out)];
+  }
+  const path = pick(input, "filePath", "file_path", "path", "file");
+  return typeof path === "string" && path ? [path] : [];
+}
+
+/** Path-scoped rules returned by `.claude/hooks/path-rules.ts`. */
+function parseRules(stdout: string): { key: string; value: string }[] {
+  try {
+    const data = JSON.parse(stdout.trim()) as { rules?: unknown };
+    if (!Array.isArray(data.rules)) return [];
+    return data.rules.filter(
+      (rule): rule is { key: string; value: string } =>
+        rule !== null &&
+        typeof rule === "object" &&
+        typeof (rule as { key?: unknown }).key === "string" &&
+        typeof (rule as { value?: unknown }).value === "string",
+    );
+  } catch {
+    return [];
+  }
+}
+
+/** Append feedback to a successful tool result so the model sees it. */
+function appendText(result: unknown, text: string): unknown {
+  const res = result as { content?: unknown } | undefined;
+  const content = res?.content;
+  if (typeof content === "string") return { ...res, content: `${content}\n\n${text}` };
+  const list = Array.isArray(content) ? content : [];
+  return { ...res, content: [...list, { type: "text", text }] };
+}
+
+export default Plugin.define({
+  id: "kataster",
+  async setup(ctx) {
+    const root = ctx.location.directory;
+
+    /** Run one hook script with a Claude-shaped payload on stdin. Never throws. */
+    function run(script: string, payload: unknown, timeout = 120_000): Promise<HookResult> {
+      return new Promise((resolve) => {
+        // The plugin itself runs inside OpenCode's bundled Bun; the hooks are plain
+        // Node scripts (type stripping), so run them with the project's Node.
+        const child = spawn(process.env.KATASTER_NODE ?? "node", [join(root, ".claude", "hooks", script)], {
+          cwd: root,
+          env: { ...process.env, CLAUDE_PROJECT_DIR: root },
+          stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8").on("data", (chunk) => (stdout += chunk));
+        child.stderr.setEncoding("utf8").on("data", (chunk) => (stderr += chunk));
+        const timer = setTimeout(() => child.kill("SIGKILL"), timeout);
+        child.on("error", (error) => {
+          clearTimeout(timer);
+          resolve({ code: 1, stdout, stderr: `${stderr}${String(error)}` });
+        });
+        child.on("close", (code) => {
+          clearTimeout(timer);
+          resolve({ code: code ?? 0, stdout, stderr });
+        });
+        child.stdin.end(JSON.stringify(payload));
+      });
+    }
+
+    // ---- Path-scoped rules ------------------------------------------------
+    // Claude Code reads `.claude/rules/` itself. OpenCode has no path-scoped rules, so the same files are
+    // attached to the session when a matching file is read or written. One entry per rule, so a rule is
+    // injected once per session and a later write to the same area does not repeat it.
+    const rulesSeen = new Map<string, Set<string>>();
+    async function injectRules(sessionID: string, tool: string, input: unknown): Promise<void> {
+      const paths = toolPaths(tool, input);
+      if (!paths.length) return;
+      try {
+        const res = await run("path-rules.ts", { paths, cwd: root }, 15_000);
+        const entries = parseRules(res.stdout);
+        if (!entries.length) return;
+        const seen = rulesSeen.get(sessionID) ?? new Set<string>();
+        rulesSeen.set(sessionID, seen);
+        for (const entry of entries) {
+          if (seen.has(entry.key)) continue;
+          seen.add(entry.key);
+          await ctx.session.instructions.entry.put({
+            sessionID: sessionID as never,
+            key: `kataster-rule:${entry.key}`,
+            value: entry.value,
+          });
+        }
+      } catch (error) {
+        // rules are guidance – never let them break a tool result
+        console.error(`[kataster] path-rules failed: ${String(error)}`);
+      }
+    }
+
+    // ---- SessionStart ------------------------------------------------------
+    // The hook prints what is missing and where the engineering work stands.
+    // An instruction entry adds it as context without starting a model turn.
+    // Child sessions (subagents) get no status block and no idle gate.
+    const controller = new AbortController();
+    const childSessions = new Set<string>();
+    void (async () => {
+      for await (const event of ctx.event.subscribe({
+        types: ["session.created"],
+        signal: controller.signal,
+      })) {
+        const data = (event as {
+          data?: { sessionID?: string; parentID?: string; location?: { directory?: string } };
+        }).data;
+        if (!data?.sessionID || data.location?.directory !== root) continue;
+        if (data.parentID) {
+          childSessions.add(data.sessionID);
+          continue;
+        }
+        const res = await run("session-start.ts", {}, 15_000);
+        const text = res.stdout.trim();
+        if (!text) continue;
+        await ctx.session.instructions.entry.put({
+          sessionID: data.sessionID as never,
+          key: "kataster-status",
+          value: text,
+        });
+      }
+    })().catch((error) => {
+      // a broken status check never blocks a session
+      console.error(`[kataster] session-start failed: ${String(error)}`);
+    });
+
+    // ---- PreToolUse: protect-files + bash-guard ----------------------------
+    await ctx.tool.hook("execute.before", async (event) => {
+      const toolName = TOOL_NAME[event.tool];
+      if (!toolName) return;
+
+      const payload = {
+        tool_name: toolName,
+        tool_input: claudeInput(event.tool, event.input),
+        cwd: root,
+        session_id: event.sessionID,
+        agent: event.agent,
+      };
+
+      if (toolName === "Bash") {
+        const res = await run("bash-guard.ts", payload, 15_000);
+        if (res.code === 2) throw new Error(res.stderr.trim() || "Blocked by bash-guard.");
+        return;
+      }
+
+      const res = await run("protect-files.ts", payload, 15_000);
+      if (res.code === 2) throw new Error(res.stderr.trim() || "Blocked by protect-files.");
+    });
+
+    // ---- PostToolUse: validate-docs + code-check + project checks ----------
+    await ctx.tool.hook("execute.after", async (event) => {
+      if (event.status !== "completed") return;
+
+      // Path-scoped rules become session context, not tool output.
+      await injectRules(event.sessionID, event.tool, event.input);
+
+      const toolName = TOOL_NAME[event.tool];
+      if (toolName !== "Write" && toolName !== "Edit" && toolName !== "MultiEdit") return;
+
+      const payload = {
+        tool_name: toolName,
+        tool_input: claudeInput(event.tool, event.input),
+        cwd: root,
+        session_id: event.sessionID,
+        agent: event.agent,
+      };
+
+      const notes: string[] = [];
+
+      const docs = await run("validate-docs.ts", payload, 60_000);
+      if (docs.code === 2) notes.push(docs.stderr.trim());
+      else {
+        const extra = additionalContext(docs.stdout);
+        if (extra) notes.push(extra);
+      }
+
+      const code = await run("code-check.ts", payload, 120_000);
+      if (code.code === 2) notes.push(code.stderr.trim());
+
+      const project = await run("project-check.ts", payload, 120_000);
+      if (project.code === 2) notes.push(project.stderr.trim());
+      else {
+        const extra = additionalContext(project.stdout);
+        if (extra) notes.push(extra);
+      }
+
+      if (notes.length) event.result = appendText(event.result, notes.join("\n\n")) as never;
+    });
+
+    // ---- Stop: the quick gate, once per user turn -------------------------
+    // `experimental.idle` runs when the session has no pending input. The first
+    // red result is fed back as a synthetic message; a new user prompt re-arms it.
+    const sentBack = new Set<string>();
+    await ctx.session.hook("prompt", (event) => {
+      sentBack.delete(event.sessionID);
+    });
+    await ctx.session.hook("experimental.idle", async (event) => {
+      if (childSessions.has(event.sessionID)) return;
+      if (sentBack.has(event.sessionID)) return;
+      const res = await run("stop-gate.ts", { stop_hook_active: false, session_id: event.sessionID }, 600_000);
+      if (res.code !== 2) return;
+      sentBack.add(event.sessionID);
+      await ctx.session.synthetic({
+        sessionID: event.sessionID,
+        text: res.stderr.trim(),
+      });
+    });
+
+    return () => controller.abort();
+  },
+});

package/AGENTS.md

@@ -0,0 +1,21 @@
+# Kataster – development entry point
+
+This repository is the **toolkit**, not an installation of it. `.claude/`, `.opencode/`, `templates/` and
+`extras/` are the payload that `npx kataster init` copies into a target repository.
+
+- **Installer:** `src/cli.mjs` (commands, prompts), `src/install.mjs` (copy, merge, manifest, upgrade),
+  `src/detect.mjs` (stack detection), `src/repo.mjs` (monorepo tooling and workspaces), `src/util.mjs`.
+- **Payload:** `.claude/` (skills, agents, hooks, lib, settings), `.opencode/` (commands, agents, plugin),
+  `templates/` (docs skeleton, project profile defaults, conventions template), `extras/` (optional skills).
+- **Tests:** `npm test` (installs into temp directories and asserts the result).
+- **Docs for users:** `README.md` and `guide/`.
+
+Rules:
+
+- The payload must stay project-neutral. No product names, no hardcoded stack, no hardcoded language. Project facts
+  come from `.claude/project.json`; examples in skills use neutral domains.
+- Every new workflow file goes into both harnesses (`.claude/agents` and `.opencode/agents`, command in
+  `.opencode/commands`) or is deliberately harness-specific and documented as such.
+- A file the installer manages is tracked in `.claude/install.json`; project content (`CONTEXT.md`, `docs/`,
+  `project.json`, `AGENTS.md` block) is not. Never make an upgrade overwrite user content.
+- Run `npm test` and `npm run typecheck --prefix .claude` before committing.