@rayburst/cc 3.0.1 → 3.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +143 -145
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,206 +4,204 @@
|
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/@rayburst/cc) [](https://github.com/Dubwoof/rayburst-cc/stargazers) [](https://github.com/Dubwoof/rayburst-cc/commits) [](LICENSE)
|
|
6
6
|
|
|
7
|
+
<p align="center">
|
|
8
|
+
<img src="claude_code_x_rayburst_prr.png" alt="Claude Code x Rayburst Product Requirement Registry" width="100%">
|
|
9
|
+
</p>
|
|
10
|
+
|
|
7
11
|
## The Problem
|
|
8
12
|
|
|
9
|
-
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.
|
|
13
|
+
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. Every conversation starts from zero — you re-explain the requirements, the edge cases, the definition of done.
|
|
10
14
|
|
|
11
|
-
Rayburst
|
|
15
|
+
Rayburst connects Claude Code to your **Product Requirement Registry (PRR)** — a structured knowledge graph of features with Gherkin acceptance criteria, managed through [rayburst.app](https://rayburst.app). The plugin makes this context **always available** to Claude without any manual commands.
|
|
12
16
|
|
|
13
|
-
|
|
14
|
-
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.
|
|
15
|
-
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.
|
|
16
|
-
4. **Atlas Protection** — Claude never creates, updates, or deletes features/criteria without asking you first.
|
|
17
|
+
## What Rayburst Does
|
|
17
18
|
|
|
18
|
-
|
|
19
|
+
Rayburst is a product management platform where you define features and their acceptance criteria. Each feature has:
|
|
19
20
|
|
|
20
|
-
|
|
21
|
+
- A **title** and **description** explaining the user-facing capability
|
|
22
|
+
- **Acceptance criteria** in Gherkin format (`Given/When/Then`) — each one atomic and testable
|
|
23
|
+
- A **status** (`draft`, `active`, `completed`, `archived`)
|
|
24
|
+
- Links to **board cards** (work items), **projects**, **tags**, and **other features**
|
|
21
25
|
|
|
22
|
-
|
|
26
|
+
The `@rayburst/cc` plugin connects Claude Code to your Rayburst organization's PRR so Claude always knows what it's building.
|
|
23
27
|
|
|
24
|
-
|
|
25
|
-
claude plugin add Dubwoof/rayburst-cc
|
|
26
|
-
```
|
|
28
|
+
## What the Plugin Does
|
|
27
29
|
|
|
28
|
-
|
|
30
|
+
The plugin is a Claude Code marketplace plugin with two parts:
|
|
29
31
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
```
|
|
32
|
+
1. **An MCP server** (stdio) that proxies 25 Rayburst API tools — Claude can read and write features, criteria, board cards, validation reports, tags, and feature links.
|
|
33
|
+
2. **Three hooks** that automatically inject product context into every Claude Code session — no slash commands needed.
|
|
33
34
|
|
|
34
|
-
|
|
35
|
-
- Your **Rayburst API key** (get one at [rayburst.app/settings/api-keys](https://www.rayburst.app/settings/api-keys))
|
|
36
|
-
- Your **project URL** (e.g. `https://www.myapp.com` or `http://localhost:3000`)
|
|
37
|
-
- **Board selection** — pick from your org's boards
|
|
38
|
-
- **Project IDs** — frontend and backend project UUIDs
|
|
39
|
-
- **User credentials** — for browser-based validation
|
|
35
|
+
### Hook 1: SessionStart
|
|
40
36
|
|
|
41
|
-
|
|
37
|
+
Fires once when a Claude Code session starts. Calls the Rayburst API to fetch all features (up to 100) and board cards, then injects them as an XML `<rayburst_product_context>` block via `additionalContext`. This block contains:
|
|
42
38
|
|
|
43
|
-
**
|
|
39
|
+
- **Six rules** that tell Claude how to work with the PRR (check atlas before coding, flag interference with other features, never modify features without user confirmation, summarize criteria coverage when done)
|
|
40
|
+
- **A compact atlas** listing every feature with its ID, status, criteria count, and title (one XML line per feature, capped at 60 features)
|
|
41
|
+
- **A board summary** showing cards in `ready`, `in-progress`, and `validation` status with their linked feature IDs
|
|
44
42
|
|
|
45
|
-
|
|
43
|
+
The hook also writes the feature list to a local cache file (`/tmp/rb-features-{hash}.json`) so the other two hooks can read it without making additional API calls.
|
|
46
44
|
|
|
47
|
-
|
|
45
|
+
If no `.claude/rb-config.md` exists or no API key is configured, the hook exits silently — the plugin is invisible until setup.
|
|
48
46
|
|
|
49
|
-
### Hook
|
|
47
|
+
### Hook 2: UserPromptSubmit
|
|
50
48
|
|
|
51
|
-
|
|
49
|
+
Fires on every user message. Reads the user's prompt from stdin, tokenizes it (removing stop words), and matches the remaining keywords against the cached feature list. Matching uses token overlap scoring with a 0.25 threshold and a bonus for exact title phrase matches.
|
|
52
50
|
|
|
53
|
-
|
|
54
|
-
<rayburst_product_context>
|
|
55
|
-
<rules>
|
|
56
|
-
<rule>Before implementing any task, check if a matching feature exists in the atlas.</rule>
|
|
57
|
-
<rule>If changes may affect OTHER features, flag this to the user.</rule>
|
|
58
|
-
<rule>NEVER modify the atlas without asking the user first.</rule>
|
|
59
|
-
<rule>When done, summarize which criteria were addressed.</rule>
|
|
60
|
-
</rules>
|
|
51
|
+
If one or more features match (up to 3), the hook calls `get_feature` on the Rayburst API for each to load full criteria, then injects an `<rayburst_active_feature>` XML block containing:
|
|
61
52
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
...
|
|
66
|
-
</atlas>
|
|
53
|
+
- The matched feature(s) with title, status, description
|
|
54
|
+
- Every acceptance criterion with its ID, status, title, and full Gherkin description
|
|
55
|
+
- A guidance line: "Work against these acceptance criteria"
|
|
67
56
|
|
|
68
|
-
|
|
69
|
-
<card id="card1" status="in-progress" features="abc123">Implement dark mode</card>
|
|
70
|
-
...
|
|
71
|
-
</board>
|
|
72
|
-
</rayburst_product_context>
|
|
73
|
-
```
|
|
57
|
+
The hook also writes the primary matched feature to a cache file (`/tmp/rb-active-feature-{hash}.json`) for the PreToolUse hook.
|
|
74
58
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
### Hook
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
<criterion id="c2" status="pending">
|
|
90
|
-
Given dark mode is active
|
|
91
|
-
When the user refreshes the page
|
|
92
|
-
Then dark mode persists
|
|
93
|
-
</criterion>
|
|
94
|
-
</feature>
|
|
95
|
-
<guidance>Work against these acceptance criteria.</guidance>
|
|
96
|
-
</rayburst_active_feature>
|
|
97
|
-
```
|
|
59
|
+
If no features match, the hook clears the active-feature cache and exits silently.
|
|
60
|
+
|
|
61
|
+
### Hook 3: PreToolUse
|
|
62
|
+
|
|
63
|
+
Fires when Claude calls `Write` or `Edit` (file creation/modification). Reads the active feature from cache and injects a `<rayburst_coding_reminder>` XML block containing:
|
|
64
|
+
|
|
65
|
+
- The active feature's name and ID
|
|
66
|
+
- A criteria checklist (unchecked `[ ]` items for each criterion)
|
|
67
|
+
- The file path being written/edited
|
|
68
|
+
- A `<related_features>` warning if the file's name or parent directory appears in the title or description of other features in the atlas
|
|
69
|
+
|
|
70
|
+
This hook makes zero API calls — it reads only from local cache files. It never blocks the tool call; it only adds context.
|
|
71
|
+
|
|
72
|
+
### MCP Server
|
|
98
73
|
|
|
99
|
-
|
|
74
|
+
A Node.js stdio server built with `@modelcontextprotocol/sdk` that proxies the Rayburst HTTP API. It reads `RAYBURST_API_KEY` from environment variables or `.claude/rb-config.md`, and calls `https://api.rayburst.app/api/v1/mcp` using JSON-RPC 2.0 over HTTP with Bearer auth.
|
|
100
75
|
|
|
101
|
-
|
|
76
|
+
The server uses a lazy client pattern — it doesn't connect to the API at startup, only on the first tool call. This means the server starts even if the API key isn't configured yet.
|
|
77
|
+
|
|
78
|
+
**25 tools across 8 domains:**
|
|
79
|
+
|
|
80
|
+
| Domain | Tools | What they do |
|
|
81
|
+
|--------|-------|-------------|
|
|
82
|
+
| **Ping** | `rb_ping` | Health check — tests API connectivity via MCP initialize handshake |
|
|
83
|
+
| **Features** | `rb_list_features`, `rb_get_feature`, `rb_create_feature`, `rb_update_feature`, `rb_delete_feature` | CRUD on features. List supports filtering by project, status, search text, and tags. Create requires title + projectIds. |
|
|
84
|
+
| **Criteria** | `rb_add_criterion`, `rb_update_criterion`, `rb_delete_criterion` | Manage acceptance criteria on features. Add requires featureId + description (Gherkin). Supports validation method (`manual`, `browser`, `code-review`). |
|
|
85
|
+
| **Board/Cards** | `rb_list_boards`, `rb_list_cards`, `rb_get_card`, `rb_create_card`, `rb_update_card`, `rb_move_card` | Board and card management. Cards have statuses: `draft`, `ready`, `in-progress`, `validation`, `done`. Get returns card with roles, todos, and dependencies. |
|
|
86
|
+
| **Card Extras** | `rb_list_card_features`, `rb_list_card_todos`, `rb_list_card_roles`, `rb_add_comment` | Read linked features/todos/roles on a card, post markdown comments. |
|
|
87
|
+
| **Links** | `rb_link_feature_to_feature`, `rb_list_feature_links` | Create typed links between features (`depends_on`, `implements`, `extends`, `related_to`). |
|
|
88
|
+
| **Validation** | `rb_submit_validation` | Submit a structured validation report for a card or feature with per-criterion pass/fail/blocked/skipped results. |
|
|
89
|
+
| **Tags** | `rb_list_tags`, `rb_create_tag` | Manage org-wide tags (18 color options) used to categorize features and criteria. |
|
|
90
|
+
|
|
91
|
+
Claude decides when to call these tools based on the rules injected by the SessionStart hook. The user never needs to invoke them manually.
|
|
92
|
+
|
|
93
|
+
## Install
|
|
102
94
|
|
|
103
|
-
|
|
95
|
+
**Prerequisites:** Claude Code v1.0.33+ and a [Rayburst](https://rayburst.app) account with an API key.
|
|
104
96
|
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
<active_feature>Dark Mode Toggle (abc123)</active_feature>
|
|
108
|
-
<criteria_checklist>
|
|
109
|
-
- [ ] Dark theme toggle on settings page
|
|
110
|
-
- [ ] Theme persists on refresh
|
|
111
|
-
- [ ] System theme detection fallback
|
|
112
|
-
</criteria_checklist>
|
|
113
|
-
<file>src/theme.ts</file>
|
|
114
|
-
<related_features>This file may also relate to: "Accessibility High Contrast".</related_features>
|
|
115
|
-
</rayburst_coding_reminder>
|
|
97
|
+
```bash
|
|
98
|
+
claude plugin add Dubwoof/rayburst-cc
|
|
116
99
|
```
|
|
117
100
|
|
|
118
|
-
|
|
101
|
+
Restart Claude Code, then run the one-time setup:
|
|
119
102
|
|
|
120
|
-
|
|
103
|
+
```
|
|
104
|
+
/rb:init
|
|
105
|
+
```
|
|
121
106
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
| **Tags** | `rb_list_tags`, `rb_create_tag` |
|
|
131
|
-
| **Health** | `rb_ping` |
|
|
107
|
+
This prompts for:
|
|
108
|
+
- **Rayburst API key** — get one at [rayburst.app/settings/api-keys](https://www.rayburst.app/settings/api-keys) (starts with `rb_user_`)
|
|
109
|
+
- **Project URL** — the base URL of your running app (e.g. `http://localhost:3000`)
|
|
110
|
+
- **Board** — picks from your org's boards via the API
|
|
111
|
+
- **Project IDs** — frontend and backend project UUIDs
|
|
112
|
+
- **User credentials** — username/password for browser-based validation (passwords can reference env vars with `$VAR_NAME`)
|
|
113
|
+
|
|
114
|
+
Config is saved to `.claude/rb-config.md`. **Add this to `.gitignore`** — it contains your API key.
|
|
132
115
|
|
|
133
|
-
|
|
116
|
+
That's it. Every Claude Code session in this project now has product context automatically.
|
|
134
117
|
|
|
135
|
-
##
|
|
118
|
+
## How a Session Looks
|
|
136
119
|
|
|
137
120
|
```
|
|
138
121
|
You: Help me implement the dark mode toggle
|
|
139
122
|
|
|
140
|
-
|
|
141
|
-
|
|
123
|
+
SessionStart hook already injected the atlas (45 features, 12 board cards)
|
|
124
|
+
UserPromptSubmit hook matches "Dark Mode Toggle" feature, loads 5 criteria
|
|
142
125
|
|
|
143
126
|
Claude: I see "Dark Mode Toggle" in your feature atlas with 5 acceptance criteria:
|
|
144
|
-
1.
|
|
145
|
-
2.
|
|
146
|
-
3.
|
|
147
|
-
4.
|
|
148
|
-
5.
|
|
127
|
+
1. Given the user is on settings, When they toggle dark mode, Then all UI switches to dark theme
|
|
128
|
+
2. Given dark mode is active, When the user refreshes, Then dark mode persists
|
|
129
|
+
3. Given no preference is set, When the app loads, Then it detects the OS theme
|
|
130
|
+
4. Given dark mode is active, When viewing any page, Then all components use dark colors
|
|
131
|
+
5. Given dark mode is toggled, When another tab is open, Then it syncs
|
|
149
132
|
|
|
150
|
-
Let me implement against these
|
|
133
|
+
Let me implement against these.
|
|
151
134
|
|
|
152
|
-
|
|
153
|
-
|
|
135
|
+
Claude calls Edit on src/theme.ts
|
|
136
|
+
PreToolUse hook injects criteria checklist + "also relates to Accessibility High Contrast"
|
|
154
137
|
|
|
155
|
-
Claude:
|
|
156
|
-
Note: this file
|
|
138
|
+
Claude: Updated src/theme.ts for theme persistence (criterion #2).
|
|
139
|
+
Note: this file also relates to "Accessibility High Contrast" —
|
|
157
140
|
my changes don't affect contrast ratio logic.
|
|
158
141
|
|
|
159
|
-
|
|
142
|
+
Claude finishes
|
|
160
143
|
|
|
161
144
|
Claude: Implementation complete. Criteria addressed:
|
|
162
|
-
- [x] Settings
|
|
163
|
-
- [x]
|
|
164
|
-
- [x]
|
|
165
|
-
- [x] All components
|
|
166
|
-
- [ ] Cross-tab sync (#5) —
|
|
145
|
+
- [x] Settings toggle (#1)
|
|
146
|
+
- [x] Persists on refresh (#2)
|
|
147
|
+
- [x] OS theme detection (#3)
|
|
148
|
+
- [x] All components (#4)
|
|
149
|
+
- [ ] Cross-tab sync (#5) — needs SharedWorker, skipped
|
|
167
150
|
|
|
168
151
|
Would you like me to update the criteria statuses in the atlas?
|
|
169
152
|
```
|
|
170
153
|
|
|
171
|
-
## The Feature Atlas
|
|
172
|
-
|
|
173
|
-
The core data model is a **feature** with **acceptance criteria** in Gherkin format:
|
|
174
|
-
|
|
175
|
-
```
|
|
176
|
-
Feature: "Card Label Management"
|
|
177
|
-
Status: active
|
|
178
|
-
|
|
179
|
-
Criteria:
|
|
180
|
-
1. Given a card exists on the board
|
|
181
|
-
When the user clicks "Add Label"
|
|
182
|
-
Then a label picker appears with available colors
|
|
183
|
-
|
|
184
|
-
2. Given a label is assigned to a card
|
|
185
|
-
When the user views the board
|
|
186
|
-
Then the label badge is visible on the card preview
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
Features link to **board cards**, **projects**, **tags**, and **other features** (dependency graph with `depends_on`, `implements`, `extends`, `related_to` links).
|
|
190
|
-
|
|
191
154
|
## Configuration
|
|
192
155
|
|
|
193
|
-
|
|
194
|
-
|--------|----------|------|
|
|
195
|
-
| Environment variables | High | `RAYBURST_API_KEY`, `RAYBURST_API_URL`, `RAYBURST_AGENT_ID` |
|
|
196
|
-
| `.claude/rb-config.md` | Normal | API key, project URL, board ID, project IDs, user credentials |
|
|
156
|
+
The plugin reads config from two sources (env vars take priority):
|
|
197
157
|
|
|
198
|
-
|
|
158
|
+
| Source | Fields |
|
|
159
|
+
|--------|--------|
|
|
160
|
+
| `RAYBURST_API_KEY` | API key (overrides config file) |
|
|
161
|
+
| `RAYBURST_API_URL` | API endpoint (default: `https://api.rayburst.app/api/v1/mcp`) |
|
|
162
|
+
| `RAYBURST_AGENT_ID` | Optional agent ID for the `X-Agent-Id` header |
|
|
163
|
+
| `.claude/rb-config.md` | API key, API URL, project URL, board ID/slug, project IDs, user credentials |
|
|
164
|
+
|
|
165
|
+
The hooks read `.claude/rb-config.md` from `$CLAUDE_PROJECT_DIR` (the directory where Claude Code was launched).
|
|
199
166
|
|
|
200
167
|
## API Key Security
|
|
201
168
|
|
|
202
|
-
-
|
|
203
|
-
-
|
|
204
|
-
-
|
|
169
|
+
- Keys are **scoped to one user + one organization** — a key cannot access other orgs
|
|
170
|
+
- Three types: `rb_user_` (human users), `rb_agent_` (AI agents), `rb_global_` (org admins)
|
|
171
|
+
- Stored in `.claude/rb-config.md` — must be gitignored
|
|
205
172
|
- Create at [rayburst.app/settings/api-keys](https://www.rayburst.app/settings/api-keys)
|
|
206
173
|
|
|
174
|
+
## File Structure
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
rayburst-cc/
|
|
178
|
+
.claude-plugin/plugin.json Plugin manifest — declares MCP server + skills
|
|
179
|
+
.mcp.json MCP server declaration (stdio)
|
|
180
|
+
start.mjs Bootstrapper — installs deps, loads server bundle
|
|
181
|
+
server.bundle.mjs Bundled MCP server (esbuild, 340kb)
|
|
182
|
+
src/
|
|
183
|
+
server.ts MCP server entry — registers 25 tools, stdio transport
|
|
184
|
+
api-client.ts HTTP client — JSON-RPC 2.0 over fetch with SSE parsing
|
|
185
|
+
tools/
|
|
186
|
+
ping.ts rb_ping
|
|
187
|
+
features.ts rb_list/get/create/update/delete_feature
|
|
188
|
+
criteria.ts rb_add/update/delete_criterion
|
|
189
|
+
board.ts rb_list_boards/cards, rb_get/create/update/move_card, rb_list_card_*
|
|
190
|
+
links.ts rb_link_feature_to_feature, rb_list_feature_links
|
|
191
|
+
validation.ts rb_submit_validation
|
|
192
|
+
tags.ts rb_list_tags, rb_create_tag
|
|
193
|
+
comments.ts rb_add_comment
|
|
194
|
+
hooks/
|
|
195
|
+
hooks.json Hook registrations (SessionStart, UserPromptSubmit, PreToolUse)
|
|
196
|
+
sessionstart.mjs Fetches atlas + board, injects <rayburst_product_context>
|
|
197
|
+
userpromptsubmit.mjs Matches prompt to features, injects <rayburst_active_feature>
|
|
198
|
+
pretooluse.mjs On Write/Edit, injects <rayburst_coding_reminder>
|
|
199
|
+
rb-cache.mjs Shared: config parsing, API calls, /tmp caching, keyword matching
|
|
200
|
+
product-context-block.mjs Shared: XML block builders for all 3 hooks
|
|
201
|
+
skills/
|
|
202
|
+
init/SKILL.md /rb:init — one-time project setup (only slash command)
|
|
203
|
+
```
|
|
204
|
+
|
|
207
205
|
## Uninstall
|
|
208
206
|
|
|
209
207
|
```bash
|
|
@@ -218,7 +216,7 @@ git clone https://github.com/Dubwoof/rayburst-cc.git
|
|
|
218
216
|
cd rayburst-cc && npm install && npm run build
|
|
219
217
|
```
|
|
220
218
|
|
|
221
|
-
|
|
219
|
+
Test locally:
|
|
222
220
|
|
|
223
221
|
```bash
|
|
224
222
|
claude plugin add /path/to/rayburst-cc
|
package/package.json
CHANGED