@rayburst/cc 2.0.0 → 3.0.0

package/.claude-plugin/plugin.json

@@ -1,13 +1,13 @@
 {
   "name": "rayburst",
-  "version": "2.0.0",
-  "description": "AI-native product management for Claude Code. Track features with acceptance criteria, validate with Playwright, and manage board cards through the full dev cycle.",
+  "version": "3.0.0",
+  "description": "Always-on product context for Claude Code. Automatically injects feature atlas and acceptance criteria into every coding session — no slash commands needed.",
   "author": {
     "name": "Rayburst",
     "email": "hello@rayburst.app"
   },
   "homepage": "https://rayburst.app",
-  "repository": "https://github.com/rayburst/rayburst-cc",
+  "repository": "https://github.com/Dubwoof/rayburst-cc",
   "license": "MIT",
   "keywords": [
     "product-management",

package/README.md

@@ -0,0 +1,229 @@
+# Rayburst
+
+**Always-on product context for Claude Code.**
+
+[![npm](https://img.shields.io/npm/v/@rayburst/cc?color=blue)](https://www.npmjs.com/package/@rayburst/cc) [![GitHub stars](https://img.shields.io/github/stars/Dubwoof/rayburst-cc?style=flat&color=yellow)](https://github.com/Dubwoof/rayburst-cc/stargazers) [![Last commit](https://img.shields.io/github/last-commit/Dubwoof/rayburst-cc?color=green)](https://github.com/Dubwoof/rayburst-cc/commits) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## The Problem
+
+You're building a feature. Claude Code writes the code, but has no idea what the feature is supposed to do. It doesn't know the acceptance criteria. It doesn't know which board card it's working on. It doesn't know what QA expects. Every conversation starts from zero — you re-explain the requirements, the edge cases, the definition of done.
+
+Rayburst solves this by giving Claude Code an **always-on product context layer**:
+
+1. **Session Context** — On every session start, Claude gets injected with your entire feature atlas: features, acceptance criteria, board cards, and their statuses. No commands needed.
+2. **Task Matching** — When you describe a task, Rayburst automatically matches it to existing features and injects the relevant Gherkin acceptance criteria. Claude knows what "done" looks like before writing a single line.
+3. **Coding Awareness** — When Claude writes or edits files, it gets reminded of the active criteria and warned if the file relates to other features that might be affected.
+4. **Atlas Protection** — Claude never creates, updates, or deletes features/criteria without asking you first.
+
+**No slash commands. No manual lookups. Just code with product context.**
+
+## Install
+
+**Prerequisites:** Claude Code v1.0.33+ and a [Rayburst](https://rayburst.app) account.
+
+```bash
+claude plugin add Dubwoof/rayburst-cc
+```
+
+Restart Claude Code, then run the one-time setup:
+
+```
+/rb:setup
+```
+
+This will prompt you for:
+- Your **Rayburst API key** (get one at [rayburst.app/settings/api-keys](https://www.rayburst.app/settings/api-keys))
+- Your **project URL** (e.g. `https://www.myapp.com` or `http://localhost:3000`)
+- **Board selection** — pick from your org's boards
+- **Project IDs** — frontend and backend project UUIDs
+- **User credentials** — for browser-based validation
+
+Config is saved to `.claude/rb-config.md` (add to `.gitignore` — contains your API key).
+
+**That's it.** From now on, every Claude Code session in this project automatically has product context.
+
+## How It Works
+
+Rayburst runs as a Claude Code plugin with **3 hooks** and an **MCP server** — all automatic, no commands needed.
+
+### Hook 1: SessionStart — Product Context Injection
+
+On every session, Rayburst fetches your feature atlas and board state, then injects it as XML context that Claude follows automatically:
+
+```xml
+<rayburst_product_context>
+  <rules>
+    <rule>Before implementing any task, check if a matching feature exists in the atlas.</rule>
+    <rule>If changes may affect OTHER features, flag this to the user.</rule>
+    <rule>NEVER modify the atlas without asking the user first.</rule>
+    <rule>When done, summarize which criteria were addressed.</rule>
+  </rules>
+
+  <atlas summary="45 features (12 draft, 28 active, 5 completed)">
+    <feature id="abc123" status="active" criteria="5">Dark Mode Toggle</feature>
+    <feature id="def456" status="draft" criteria="3">Monthly Billing</feature>
+    ...
+  </atlas>
+
+  <board summary="12 cards — 3 in-progress, 2 validation, 5 done">
+    <card id="card1" status="in-progress" features="abc123">Implement dark mode</card>
+    ...
+  </board>
+</rayburst_product_context>
+```
+
+Claude starts every conversation knowing every feature, its status, and the board state.
+
+### Hook 2: UserPromptSubmit — Automatic Feature Matching
+
+When you type a message, Rayburst matches your words against feature titles and descriptions. If a match is found, it loads the full acceptance criteria and injects them:
+
+```xml
+<rayburst_active_feature>
+  <feature id="abc123" title="Dark Mode Toggle" status="active">
+    <criterion id="c1" status="pending">
+      Given the user is on the settings page
+      When they toggle dark mode
+      Then all UI elements switch to dark theme
+    </criterion>
+    <criterion id="c2" status="pending">
+      Given dark mode is active
+      When the user refreshes the page
+      Then dark mode persists
+    </criterion>
+  </feature>
+  <guidance>Work against these acceptance criteria.</guidance>
+</rayburst_active_feature>
+```
+
+Claude immediately knows what it's building and what the acceptance criteria are — without you pasting requirements.
+
+### Hook 3: PreToolUse — Coding Reminders
+
+When Claude writes or edits a file, Rayburst injects a reminder of the active criteria and flags if the file relates to other features:
+
+```xml
+<rayburst_coding_reminder>
+  <active_feature>Dark Mode Toggle (abc123)</active_feature>
+  <criteria_checklist>
+    - [ ] Dark theme toggle on settings page
+    - [ ] Theme persists on refresh
+    - [ ] System theme detection fallback
+  </criteria_checklist>
+  <file>src/theme.ts</file>
+  <related_features>This file may also relate to: "Accessibility High Contrast".</related_features>
+</rayburst_coding_reminder>
+```
+
+### MCP Server (25 tools)
+
+Claude can call Rayburst tools directly when it needs to interact with the atlas:
+
+| Domain | Tools |
+|--------|-------|
+| **Features** | `rb_list_features`, `rb_get_feature`, `rb_create_feature`, `rb_update_feature`, `rb_delete_feature` |
+| **Criteria** | `rb_add_criterion`, `rb_update_criterion`, `rb_delete_criterion` |
+| **Board** | `rb_list_boards`, `rb_list_cards`, `rb_get_card`, `rb_create_card`, `rb_update_card`, `rb_move_card` |
+| **Card Extras** | `rb_list_card_features`, `rb_list_card_todos`, `rb_list_card_roles`, `rb_add_comment` |
+| **Links** | `rb_link_feature_to_feature`, `rb_list_feature_links` |
+| **Validation** | `rb_submit_validation` |
+| **Tags** | `rb_list_tags`, `rb_create_tag` |
+| **Health** | `rb_ping` |
+
+Claude decides when to call these based on the injected rules — you never need to.
+
+## Example Session
+
+```
+You: Help me implement the dark mode toggle
+
+  [SessionStart already injected atlas with 45 features]
+  [UserPromptSubmit matches "Dark Mode Toggle", injects 5 criteria]
+
+Claude: I see "Dark Mode Toggle" in your feature atlas with 5 acceptance criteria:
+  1. Settings page toggle switches to dark theme
+  2. Theme persists on refresh
+  3. System theme detection as default
+  4. Dark mode applies to all components
+  5. Toggle state syncs across tabs
+
+Let me implement against these criteria.
+
+  [Claude edits src/theme.ts]
+  [PreToolUse injects criteria checklist + "also relates to Accessibility High Contrast"]
+
+Claude: I've updated src/theme.ts to handle theme persistence (criterion #2).
+Note: this file is also used by the "Accessibility High Contrast" feature —
+my changes don't affect contrast ratio logic.
+
+  [Claude finishes implementation]
+
+Claude: Implementation complete. Criteria addressed:
+  - [x] Settings page toggle (#1)
+  - [x] Theme persists on refresh (#2)
+  - [x] System theme detection (#3)
+  - [x] All components themed (#4)
+  - [ ] Cross-tab sync (#5) — requires SharedWorker, skipped for now
+
+Would you like me to update the criteria statuses in the atlas?
+```
+
+## The Feature Atlas
+
+The core data model is a **feature** with **acceptance criteria** in Gherkin format:
+
+```
+Feature: "Card Label Management"
+  Status: active
+
+  Criteria:
+    1. Given a card exists on the board
+       When the user clicks "Add Label"
+       Then a label picker appears with available colors
+
+    2. Given a label is assigned to a card
+       When the user views the board
+       Then the label badge is visible on the card preview
+```
+
+Features link to **board cards**, **projects**, **tags**, and **other features** (dependency graph with `depends_on`, `implements`, `extends`, `related_to` links).
+
+## Configuration
+
+| Source | Priority | What |
+|--------|----------|------|
+| Environment variables | High | `RAYBURST_API_KEY`, `RAYBURST_API_URL`, `RAYBURST_AGENT_ID` |
+| `.claude/rb-config.md` | Normal | API key, project URL, board ID, project IDs, user credentials |
+
+Environment variables override config file values. Most users just run `/rb:setup` once.
+
+## API Key Security
+
+- API keys are **scoped to one user + one organization** — cannot access other orgs
+- Stored in `.claude/rb-config.md` — add to `.gitignore`
+- Three types: `rb_user_` (humans), `rb_agent_` (AI agents), `rb_global_` (org admins)
+- Create at [rayburst.app/settings/api-keys](https://www.rayburst.app/settings/api-keys)
+
+## Uninstall
+
+```bash
+claude plugin remove rayburst
+rm .claude/rb-config.md
+```
+
+## Contributing
+
+```bash
+git clone https://github.com/Dubwoof/rayburst-cc.git
+cd rayburst-cc && npm install && npm run build
+```
+
+MCP server in `src/`, hooks in `hooks/`, setup skill in `skills/setup/`.
+
+```bash
+claude plugin add /path/to/rayburst-cc
+```
+
+## License
+
+MIT

package/hooks/hooks.json

@@ -10,6 +10,37 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/userpromptsubmit.mjs"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.mjs"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.mjs"
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/pretooluse.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse hook for the Rayburst plugin.
+ *
+ * Triggered on Write and Edit tool calls. Reads the active feature
+ * from cache and injects a coding reminder with criteria checklist.
+ */
+
+import { readCache } from "./rb-cache.mjs";
+import { buildCodingReminderBlock } from "./product-context-block.mjs";
+
+// Read stdin for the hook input
+let input = "";
+try {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  input = Buffer.concat(chunks).toString("utf-8");
+} catch {
+  process.exit(0);
+}
+
+let hookInput;
+try {
+  hookInput = JSON.parse(input);
+} catch {
+  process.exit(0);
+}
+
+const toolName = hookInput?.input?.tool_name;
+const toolInput = hookInput?.input?.tool_input;
+
+// Only act on Write and Edit
+if (toolName !== "Write" && toolName !== "Edit") {
+  process.exit(0);
+}
+
+// Read active feature from cache
+const activeFeature = readCache("active-feature");
+if (!activeFeature) {
+  process.exit(0);
+}
+
+// Get the file path being edited
+const filePath = toolInput?.file_path || toolInput?.path || "";
+
+// Check if other features mention this file path (basic matching)
+const featureList = readCache("features") || [];
+const relatedFeatures = [];
+
+if (filePath) {
+  const fileBasename = filePath.split("/").pop() || "";
+  const fileDir = filePath.split("/").slice(-2, -1)[0] || "";
+
+  for (const f of featureList) {
+    if (f.id === activeFeature.id) continue;
+    const desc = (f.description || "").toLowerCase();
+    const title = (f.title || "").toLowerCase();
+    if (
+      desc.includes(fileBasename.toLowerCase()) ||
+      desc.includes(fileDir.toLowerCase()) ||
+      title.includes(fileBasename.toLowerCase().replace(/\.\w+$/, ""))
+    ) {
+      relatedFeatures.push(f);
+    }
+  }
+}
+
+// Build and inject the Coding Reminder Block
+const contextBlock = buildCodingReminderBlock(
+  activeFeature,
+  filePath,
+  relatedFeatures.slice(0, 3)
+);
+
+if (contextBlock) {
+  console.log(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext: contextBlock,
+      },
+    })
+  );
+}

package/hooks/product-context-block.mjs

@@ -0,0 +1,131 @@
+/**
+ * XML block builders for Rayburst hook context injection.
+ */
+
+/**
+ * Build the main Product Context Block injected at session start.
+ * Contains rules, feature atlas summary, and board summary.
+ */
+export function buildProductContextBlock(features, cards) {
+  const featureList = Array.isArray(features) ? features : features?.data ?? [];
+  const cardList = Array.isArray(cards) ? cards : cards?.data ?? [];
+
+  // Count features by status
+  const counts = { draft: 0, active: 0, completed: 0, archived: 0 };
+  for (const f of featureList) {
+    counts[f.status || "draft"] = (counts[f.status || "draft"] || 0) + 1;
+  }
+  const total = featureList.length;
+
+  // Count cards by status
+  const cardCounts = {};
+  for (const c of cardList) {
+    cardCounts[c.status || "draft"] = (cardCounts[c.status || "draft"] || 0) + 1;
+  }
+
+  // Build feature lines (compact: one line each)
+  const featureLines = featureList
+    .slice(0, 60)
+    .map((f) => {
+      const critCount = f.criteriaCount ?? f.criteria?.length ?? "?";
+      return `    <feature id="${f.id}" status="${f.status}" criteria="${critCount}">${escapeXml(f.title)}</feature>`;
+    })
+    .join("\n");
+
+  const truncated =
+    featureList.length > 60
+      ? `\n    <truncated shown="60" total="${featureList.length}"/>`
+      : "";
+
+  // Build card lines
+  const activeCards = cardList.filter(
+    (c) => c.status === "in-progress" || c.status === "validation" || c.status === "ready"
+  );
+  const cardLines = activeCards
+    .slice(0, 20)
+    .map((c) => {
+      const featureIds = (c.features || []).map((f) => f.id || f).join(",");
+      return `    <card id="${c.id}" status="${c.status}" features="${featureIds}">${escapeXml(c.title)}</card>`;
+    })
+    .join("\n");
+
+  return `<rayburst_product_context>
+  <rules>
+    <rule>You have access to a Rayburst feature atlas — a knowledge graph of product features with Gherkin acceptance criteria. Use it to understand what you're building.</rule>
+    <rule>Before implementing any task, check if a matching feature exists in the atlas below. If found, read its criteria with rb_get_feature and work against them.</rule>
+    <rule>If your changes may affect behaviors described in OTHER features' criteria, flag this to the user before proceeding.</rule>
+    <rule>NEVER create, update, or delete features or criteria in the atlas without explicitly asking the user for confirmation first. Show them what you want to change and wait for approval.</rule>
+    <rule>When implementation is complete, summarize which acceptance criteria were addressed and which remain pending.</rule>
+    <rule>Use mcp__plugin_rayburst_rayburst__rb_* MCP tools to interact with the atlas. Use rb_get_feature to load full criteria for a specific feature.</rule>
+  </rules>
+
+  <atlas summary="${total} features (${counts.draft} draft, ${counts.active} active, ${counts.completed} completed)">
+${featureLines}${truncated}
+  </atlas>
+
+  <board summary="${cardList.length} cards — ${cardCounts["in-progress"] || 0} in-progress, ${cardCounts["validation"] || 0} validation, ${cardCounts["done"] || 0} done">
+${cardLines}
+  </board>
+</rayburst_product_context>`;
+}
+
+/**
+ * Build the Active Feature Block injected when a user prompt matches a feature.
+ * Contains full criteria for the matched feature(s).
+ */
+export function buildActiveFeatureBlock(features) {
+  if (!features || features.length === 0) return "";
+
+  const featureBlocks = features.map((f) => {
+    const criteria = (f.criteria || [])
+      .map((c) => {
+        return `    <criterion id="${c.id}" status="${c.status}">${escapeXml(c.title || "")} — ${escapeXml(c.description || "")}</criterion>`;
+      })
+      .join("\n");
+
+    return `  <feature id="${f.id}" title="${escapeXml(f.title)}" status="${f.status}">
+    <description>${escapeXml(f.description || "")}</description>
+${criteria}
+  </feature>`;
+  });
+
+  return `<rayburst_active_feature>
+${featureBlocks.join("\n")}
+  <guidance>Work against these acceptance criteria. When done, summarize which criteria your changes address and which remain.</guidance>
+</rayburst_active_feature>`;
+}
+
+/**
+ * Build the Coding Reminder Block injected before Write/Edit calls.
+ */
+export function buildCodingReminderBlock(activeFeature, filePath, relatedFeatures) {
+  if (!activeFeature) return "";
+
+  const criteria = (activeFeature.criteria || [])
+    .map((c) => `  - [ ] ${escapeXml(c.title || c.description || "")}`)
+    .join("\n");
+
+  let relatedNote = "";
+  if (relatedFeatures && relatedFeatures.length > 0) {
+    const names = relatedFeatures
+      .map((f) => `"${escapeXml(f.title)}"`)
+      .join(", ");
+    relatedNote = `\n  <related_features>This file may also relate to: ${names}. Check that your changes don't break their criteria.</related_features>`;
+  }
+
+  return `<rayburst_coding_reminder>
+  <active_feature>${escapeXml(activeFeature.title)} (${activeFeature.id})</active_feature>
+  <criteria_checklist>
+${criteria}
+  </criteria_checklist>
+  <file>${escapeXml(filePath || "unknown")}</file>${relatedNote}
+</rayburst_coding_reminder>`;
+}
+
+function escapeXml(str) {
+  return (str || "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}