@rudderhq/server 0.1.0-canary.0

package/resources/bundled-skills/rudder-create-plugin/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: rudder-create-plugin
+description: Create new Rudder plugins with the current alpha SDK/runtime. Use when scaffolding a plugin package, adding a new example plugin, or updating plugin authoring docs. Covers the supported worker/UI surface, route conventions, scaffold flow, and verification steps.
+  Create new Rudder plugins with the current alpha SDK/runtime. Use when
+  scaffolding a plugin package, adding a new example plugin, or updating plugin
+  authoring docs. Covers the supported worker/UI surface, route conventions,
+  scaffold flow, and verification steps.
+allowed-tools: 
+disable: true
+---
+
+# Create a Rudder Plugin
+
+Use this skill when the task is to create, scaffold, or document a Rudder plugin.
+
+## 1. Ground rules
+
+Read these first when needed:
+
+1. `doc/plugins/PLUGIN_AUTHORING_GUIDE.md`
+2. `packages/plugins/sdk/README.md`
+3. `doc/plugins/PLUGIN_SPEC.md` only for future-looking context
+
+Current runtime assumptions:
+
+- plugin workers are trusted code
+- plugin UI is trusted same-origin host code
+- worker APIs are capability-gated
+- plugin UI is not sandboxed by manifest capabilities
+- no host-provided shared plugin UI component kit yet
+- `ctx.assets` is not supported in the current runtime
+
+## 2. Preferred workflow
+
+Use the scaffold package instead of hand-writing the boilerplate:
+
+```bash
+pnpm --filter @rudderhq/create-rudder-plugin build
+node packages/plugins/create-rudder-plugin/dist/index.js <npm-package-name> --output <target-dir>
+```
+
+For a plugin that lives outside the Rudder repo, pass `--sdk-path` and let the scaffold snapshot the local SDK/shared packages into `.rudder-sdk/`:
+
+```bash
+pnpm --filter @rudderhq/create-rudder-plugin build
+node packages/plugins/create-rudder-plugin/dist/index.js @acme/plugin-name \
+  --output /absolute/path/to/plugin-repos \
+  --sdk-path /absolute/path/to/rudder/packages/plugins/sdk
+```
+
+Recommended target inside this repo:
+
+- `packages/plugins/examples/` for example plugins
+- another `packages/plugins/<name>/` folder if it is becoming a real package
+
+## 3. After scaffolding
+
+Check and adjust:
+
+- `src/manifest.ts`
+- `src/worker.ts`
+- `src/ui/index.tsx`
+- `tests/plugin.spec.ts`
+- `package.json`
+
+Make sure the plugin:
+
+- declares only supported capabilities
+- does not use `ctx.assets`
+- does not import host UI component stubs
+- keeps UI self-contained
+- uses `routePath` only on `page` slots
+- is installed into Rudder from an absolute local path during development
+
+## 4. If the plugin should appear in the app
+
+For bundled example/discoverable behavior, update the relevant host wiring:
+
+- bundled example list in `server/src/routes/plugins.ts`
+- any docs that list in-repo examples
+
+Only do this if the user wants the plugin surfaced as a bundled example.
+
+## 5. Verification
+
+Always run:
+
+```bash
+pnpm --filter <plugin-package> typecheck
+pnpm --filter <plugin-package> test
+pnpm --filter <plugin-package> build
+```
+
+If you changed SDK/host/plugin runtime code too, also run broader repo checks as appropriate.
+
+## 6. Documentation expectations
+
+When authoring or updating plugin docs:
+
+- distinguish current implementation from future spec ideas
+- be explicit about the trusted-code model
+- do not promise host UI components or asset APIs
+- prefer npm-package deployment guidance over repo-local workflows for production

package/resources/community-skills/deep-research/README.md

@@ -0,0 +1,124 @@
+# Deep Research Skill for Claude Code
+
+Enterprise-grade research engine for Claude Code. Produces citation-backed reports with source credibility scoring, multi-provider search, automated validation, and concrete cases/examples that make abstract findings easier to grasp.
+
+## Installation
+
+```bash
+# Clone into Claude Code skills directory
+git clone https://github.com/199-biotechnologies/claude-deep-research-skill.git ~/.claude/skills/deep-research
+```
+
+No additional dependencies required for basic usage.
+
+### Optional: search-cli (multi-provider search)
+
+For aggregated search across Brave, Serper, Exa, Jina, and Firecrawl:
+
+```bash
+brew tap 199-biotechnologies/tap && brew install search-cli
+search config set keys.brave YOUR_KEY  # configure at least one provider
+```
+
+## Usage
+
+```
+deep research on the current state of quantum computing
+```
+
+```
+deep research in ultradeep mode: compare PostgreSQL vs Supabase for our stack
+```
+
+## Research Modes
+
+| Mode | Phases | Duration | Best For |
+|------|--------|----------|----------|
+| Quick | 3 | 2-5 min | Initial exploration |
+| Standard | 6 | 5-10 min | Most research questions |
+| Deep | 8 | 10-20 min | Complex topics, critical decisions |
+| UltraDeep | 8+ | 20-45 min | Comprehensive reports, maximum rigor |
+
+## Pipeline
+
+Scope → Plan → **Retrieve** (parallel search + agents) → Triangulate → Outline Refinement → Synthesize → Critique (with loop-back) → Refine → Package
+
+Key features:
+- **Step 0**: Retrieves current date before searches (prevents stale training-data year assumptions)
+- **Parallel retrieval**: 5-10 concurrent searches + 2-3 focused sub-agents returning structured evidence objects
+- **First Finish Search**: Adaptive quality thresholds by mode
+- **Critique loop-back**: Phase 6 can return to Phase 3 with delta-queries if critical gaps found
+- **Multi-persona red teaming**: Skeptical Practitioner, Adversarial Reviewer, Implementation Engineer (Deep/UltraDeep)
+- **Disk-persisted citations**: `sources.json` survives context compaction and continuation agents
+- **Case-grounded synthesis**: Encourages source-grounded examples, mini-cases, counterexamples, and labeled hypotheticals for technical or abstract findings
+
+## Output
+
+Reports saved to `~/Documents/[Topic]_Research_[Date]/`:
+- Markdown (primary source of truth)
+- HTML (McKinsey-style, auto-opened in browser)
+- PDF (professional print via WeasyPrint)
+
+Major findings should be grounded in concrete examples or mini-cases when that improves readability. Prefer real sourced cases; if only a hypothetical illustration is possible, label it explicitly.
+
+Reports >18K words auto-continue via recursive agent spawning with context preservation.
+
+## Quality Standards
+
+- 10+ sources, 3+ per major claim
+- Executive summary 200-400 words
+- Findings 600-2,000 words each, prose-first (>=80%)
+- Major findings grounded in concrete examples, cases, counterexamples, or applied scenarios when helpful
+- Full bibliography with URLs, no placeholders
+- Automated validation: `validate_report.py` (10 checks) + `verify_citations.py` (DOI/URL/hallucination detection)
+- Validation loop: validate → fix → retry (max 3 cycles)
+
+## Search Tools
+
+| Tool | When | Setup |
+|------|------|-------|
+| WebSearch | Default, always available | None |
+| Exa MCP | Semantic/neural search | MCP config |
+| search-cli | Multi-provider aggregation | `brew install search-cli` + API keys |
+
+## Architecture
+
+```
+deep-research/
+├── SKILL.md                          # Skill entry point (lean, ~100 lines)
+├── reference/
+│   ├── methodology.md                # 8-phase pipeline details
+│   ├── report-assembly.md            # Progressive generation strategy
+│   ├── quality-gates.md              # Validation standards
+│   ├── html-generation.md            # McKinsey HTML conversion
+│   ├── continuation.md               # Auto-continuation protocol
+│   └── weasyprint_guidelines.md      # PDF generation
+├── templates/
+│   ├── report_template.md            # Report structure template
+│   └── mckinsey_report_template.html # HTML report template
+├── scripts/
+│   ├── validate_report.py            # 10-check structure validator
+│   ├── verify_citations.py           # DOI/URL/hallucination checker
+│   ├── source_evaluator.py           # Source credibility scoring
+│   ├── citation_manager.py           # Citation tracking
+│   ├── md_to_html.py                 # Markdown to HTML converter
+│   ├── verify_html.py                # HTML verification
+│   └── research_engine.py            # Core orchestration engine
+└── tests/
+    └── fixtures/                     # Test report fixtures
+```
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 2.3.2 | 2026-04-05 | Case-grounded readability improvements across skill instructions, templates, and validation heuristics |
+| 2.3.1 | 2026-03-19 | Template/validator harmonization, structured evidence, critique loop-back, multi-persona red teaming |
+| 2.3 | 2026-03-19 | Contract harmonization, search-cli integration, dynamic year detection, disk-persisted citations, validation loops |
+| 2.2 | 2025-11-05 | Auto-continuation system for unlimited length |
+| 2.1 | 2025-11-05 | Progressive file assembly |
+| 1.0 | 2025-11-04 | Initial release |
+
+## License
+
+MIT - modify as needed for your workflow.

package/resources/community-skills/deep-research/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: deep-research
+description: Conducts enterprise-grade research with multi-source synthesis, citation tracking, and verification. Produces citation-backed reports through a structured pipeline with source credibility scoring, and grounds abstract findings in concrete examples, cases, counterexamples, or mini-scenarios when helpful. Triggers on "deep research", "comprehensive analysis", "research report", "compare X vs Y", "analyze trends", or "state of the art". Not for simple lookups, debugging, or questions answerable with 1-2 searches.
+---
+
+# Deep Research
+
+## Core Purpose
+
+Deliver citation-backed, verified research reports through a structured pipeline with source credibility scoring, evidence persistence, and progressive context management.
+
+**Autonomy Principle:** Operate independently. Infer assumptions from context. Only stop for critical errors or incomprehensible queries.
+
+**Accessibility Principle:** Make dense analysis easier to grasp. When a finding is abstract, architectural, process-heavy, or strategically subtle, ground it in a concrete example, mini-case, counterexample, implementation scenario, or failure mode. Prefer real source-grounded cases; if you use an illustrative hypothetical, label it clearly as hypothetical and do not cite it as if it were sourced fact.
+
+---
+
+## Decision Tree
+
+```
+Request Analysis
++-- Simple lookup? --> STOP: Use WebSearch
++-- Debugging? --> STOP: Use standard tools
++-- Complex analysis needed? --> CONTINUE
+
+Mode Selection
++-- Initial exploration --> quick (3 phases, 2-5 min)
++-- Standard research --> standard (6 phases, 5-10 min) [DEFAULT]
++-- Critical decision --> deep (8 phases, 10-20 min)
++-- Comprehensive review --> ultradeep (8+ phases, 20-45 min)
+```
+
+**Default assumptions:** Technical query = technical audience. Comparison = balanced perspective. Trend = recent 1-2 years.
+
+**Default readability rule:** For Standard mode and above, try to include at least one concrete case/example for each major finding unless the topic is purely numeric, the source material provides no credible case material, or confidentiality/safety considerations make cases inappropriate.
+
+---
+
+## Workflow Overview
+
+| Phase | Name | Quick | Standard | Deep | UltraDeep |
+|-------|------|-------|----------|------|-----------|
+| 1 | SCOPE | Y | Y | Y | Y |
+| 2 | PLAN | - | Y | Y | Y |
+| 3 | RETRIEVE | Y | Y | Y | Y |
+| 4 | TRIANGULATE | - | Y | Y | Y |
+| 4.5 | OUTLINE REFINEMENT | - | Y | Y | Y |
+| 5 | SYNTHESIZE | - | Y | Y | Y |
+| 6 | CRITIQUE | - | - | Y | Y |
+| 7 | REFINE | - | - | Y | Y |
+| 8 | PACKAGE | Y | Y | Y | Y |
+
+---
+
+## Execution
+
+**On invocation, load relevant reference files:**
+
+1. **Phase 1-7:** Load [methodology.md](./reference/methodology.md) for detailed phase instructions
+2. **Phase 8 (Report):** Load [report-assembly.md](./reference/report-assembly.md) for progressive generation
+3. **HTML/PDF output:** Load [html-generation.md](./reference/html-generation.md)
+4. **Quality checks:** Load [quality-gates.md](./reference/quality-gates.md)
+5. **Long reports (>18K words):** Load [continuation.md](./reference/continuation.md)
+
+**Templates:**
+- Report structure: [report_template.md](./templates/report_template.md)
+- HTML styling: [mckinsey_report_template.html](./templates/mckinsey_report_template.html)
+
+**Scripts:**
+- `python scripts/validate_report.py --report [path]`
+- `python scripts/verify_citations.py --report [path]`
+- `python scripts/md_to_html.py [markdown_path]`
+
+---
+
+## Output Contract
+
+**Required sections:**
+- Executive Summary (200-400 words)
+- Introduction (scope, methodology, assumptions)
+- Main Analysis (4-8 findings, 600-2,000 words each, cited, each grounded in concrete examples/cases when helpful)
+- Synthesis & Insights (patterns, implications)
+- Limitations & Caveats
+- Recommendations
+- Bibliography (COMPLETE - every citation, no placeholders)
+- Methodology Appendix
+
+**Output files (all to `~/Documents/[Topic]_Research_[YYYYMMDD]/`):**
+- Markdown (primary source)
+- HTML (McKinsey style, auto-opened)
+- PDF (professional print, auto-opened)
+
+**Quality standards:**
+- 10+ sources, 3+ per major claim
+- All claims cited immediately [N]
+- No placeholders, no fabricated citations
+- Prose-first (>=80%), bullets sparingly
+- Use concrete examples, mini-cases, counterexamples, or applied scenarios to make major findings easier to understand
+- Source-ground real cases when available; clearly label hypothetical illustrative examples instead of citing them as factual evidence
+
+---
+
+## When to Use / NOT Use
+
+**Use:** Comprehensive analysis, technology comparisons, state-of-the-art reviews, multi-perspective investigation, market analysis.
+
+**Do NOT use:** Simple lookups, debugging, 1-2 search answers, quick time-sensitive queries.

package/resources/community-skills/deep-research/reference/continuation.md

@@ -0,0 +1,169 @@
+# Auto-Continuation Protocol
+
+## When to Use
+
+Trigger auto-continuation when report exceeds 18,000 words in single run.
+
+---
+
+## Strategy Overview
+
+1. Generate sections 1-10 (stay under 18K words)
+2. Save continuation state file with context preservation
+3. Spawn continuation agent via Task tool
+4. Continuation agent: Reads state -> Generates next batch -> Spawns next if needed
+5. Chain continues recursively until complete
+
+---
+
+## Continuation State File
+
+**Location:** `~/.claude/research_output/continuation_state_[report_id].json`
+
+```json
+{
+  "version": "2.1.1",
+  "report_id": "[unique_id]",
+  "file_path": "[absolute_path_to_report.md]",
+  "mode": "[quick|standard|deep|ultradeep]",
+
+  "progress": {
+    "sections_completed": ["list of section IDs"],
+    "total_planned_sections": 15,
+    "word_count_so_far": 12000,
+    "continuation_count": 1
+  },
+
+  "citations": {
+    "used": [1, 2, 3, "...", "N"],
+    "next_number": 45,
+    "bibliography_entries": [
+      "[1] Full citation entry",
+      "[2] Full citation entry"
+    ]
+  },
+
+  "research_context": {
+    "research_question": "[original question]",
+    "key_themes": ["theme1", "theme2"],
+    "main_findings_summary": [
+      "Finding 1: [100-word summary]",
+      "Finding 2: [100-word summary]"
+    ],
+    "narrative_arc": "middle"
+  },
+
+  "quality_metrics": {
+    "avg_words_per_finding": 1500,
+    "citation_density": 5.2,
+    "prose_vs_bullets_ratio": "85% prose",
+    "writing_style": "technical-precise-data-driven"
+  },
+
+  "next_sections": [
+    {"id": 11, "type": "finding", "title": "Finding X", "target_words": 1500},
+    {"id": 12, "type": "synthesis", "title": "Synthesis", "target_words": 1000}
+  ]
+}
+```
+
+---
+
+## Spawning Continuation Agent
+
+Use Task tool:
+
+```
+Task(
+  subagent_type="general-purpose",
+  description="Continue deep-research report generation",
+  prompt="""
+CONTINUATION TASK: Continue existing deep-research report.
+
+CRITICAL INSTRUCTIONS:
+1. Read continuation state: ~/.claude/research_output/continuation_state_[report_id].json
+2. Read existing report: [file_path from state]
+3. Read LAST 3 completed sections for flow/style
+4. Load research context: themes, narrative arc, writing style
+5. Continue citation numbering from state.citations.next_number
+6. Maintain quality metrics (avg words, citation density, prose ratio)
+
+YOUR TASK:
+Generate next batch (stay under 18,000 words):
+[List next_sections from state]
+
+Use Write/Edit to append to: [file_path]
+
+QUALITY GATES:
+- Words per section: Within +/-20% of avg_words_per_finding
+- Citation density: Match +/-0.5 per 1K words
+- Prose ratio: Maintain >=80%
+- Theme alignment: Section ties to key_themes
+
+After generating:
+- If more sections remain: Update state, spawn next agent
+- If final sections: Generate bibliography, verify report, cleanup state
+"""
+)
+```
+
+---
+
+## Continuation Agent Quality Protocol
+
+### Context Loading (CRITICAL)
+
+1. Read continuation_state.json -> Load ALL context
+2. Read existing report file -> Review last 3 sections
+3. Extract patterns:
+   - Sentence structure complexity
+   - Technical terminology used
+   - Citation placement patterns
+   - Paragraph transition style
+
+### Pre-Generation Checklist
+
+- [ ] Loaded research context (themes, question, narrative arc)
+- [ ] Reviewed previous sections for flow
+- [ ] Loaded citation numbering (start from N+1)
+- [ ] Loaded quality targets (words, density, style)
+- [ ] Understand narrative position (beginning/middle/end)
+
+### Per-Section Generation
+
+1. Generate section content
+2. Quality checks:
+   - Word count within +/-20%
+   - Citation density matches
+   - Prose ratio >=80%
+   - Theme connection verified
+   - Style consistent
+3. If ANY fails: Regenerate
+4. If passes: Write to file, update state
+
+### Handoff Decision
+
+Calculate: Current words + remaining sections x avg_words_per_section
+- If total < 18K: Generate all + finish
+- If total > 18K: Generate partial, update state, spawn next agent
+
+### Final Agent Responsibilities
+
+- Generate final content sections
+- Generate COMPLETE bibliography from state.citations.bibliography_entries
+- Read entire assembled report
+- Run validation: `python scripts/validate_report.py --report [path]`
+- Delete continuation_state.json (cleanup)
+- Report complete to user
+
+---
+
+## User Communication
+
+After spawning continuation:
+```
+Report Generation: Part 1 Complete (N sections, X words)
+Auto-continuing via spawned agent...
+   Next batch: [section list]
+   Progress: [X%] complete
+```

package/resources/community-skills/deep-research/reference/html-generation.md

@@ -0,0 +1,103 @@
+# HTML Generation: McKinsey Style Report
+
+## Design Principles
+
+- Sharp corners (NO border-radius)
+- Muted corporate colors (navy #003d5c, gray #f8f9fa)
+- Ultra-compact layout
+- Info-first structure
+- 14px base font, compact spacing
+- No decorative gradients or colors
+- NO EMOJIS in final HTML
+
+---
+
+## Generation Steps
+
+### Step 1: Read McKinsey Template
+Load template from: `./templates/mckinsey_report_template.html`
+
+### Step 2: Extract Key Metrics
+Extract 3-4 key quantitative findings for dashboard display at top.
+
+### Step 3: Convert MD to HTML
+
+Use Python script:
+```bash
+cd ~/.claude/skills/deep-research
+python scripts/md_to_html.py [markdown_report_path]
+```
+
+**Script outputs two parts:**
+- **Part A ({{CONTENT}}):** All sections except Bibliography
+- **Part B ({{BIBLIOGRAPHY}}):** Bibliography section only
+
+**Script handles all conversion:**
+- Headers: `##` -> `<div class="section"><h2 class="section-title">`
+- Headers: `###` -> `<h3 class="subsection-title">`
+- Lists: Markdown bullets -> `<ul><li>` with nesting
+- Tables: Markdown tables -> `<table>` with thead/tbody
+- Paragraphs: Text wrapped in `<p>` tags
+- Bold/italic: `**text**` -> `<strong>`, `*text*` -> `<em>`
+- Citations: [N] preserved for tooltip conversion
+
+### Step 4: Add Citation Tooltips (Optional)
+
+Attribution Gradients - wrap each [N] citation:
+```html
+<span class="citation">[N]
+  <span class="citation-tooltip">
+    <div class="tooltip-title">[Source Title]</div>
+    <div class="tooltip-source">[Author/Publisher]</div>
+    <div class="tooltip-claim">
+      <div class="tooltip-claim-label">Supports Claim:</div>
+      [Extract sentence with this citation]
+    </div>
+  </span>
+</span>
+```
+NOTE: This step is optional for speed. Basic [N] citations are sufficient.
+
+### Step 5: Replace Template Placeholders
+
+| Placeholder | Content |
+|-------------|---------|
+| {{TITLE}} | Report title (from first ## heading) |
+| {{DATE}} | Generation date (YYYY-MM-DD) |
+| {{SOURCE_COUNT}} | Number of unique sources |
+| {{METRICS_DASHBOARD}} | Metrics HTML from step 2 |
+| {{CONTENT}} | HTML from Part A |
+| {{BIBLIOGRAPHY}} | HTML from Part B |
+
+### Step 6: Verify HTML
+
+```bash
+python scripts/verify_html.py --html [html_path] --md [md_path]
+```
+- Pass: Proceed to open
+- Fail: Fix errors and re-run
+
+### Step 7: Open in Browser
+```bash
+open [html_path]
+```
+
+---
+
+## PDF Generation
+
+**Option A: WeasyPrint Direct (Preferred)**
+
+1. Create print-optimized HTML following `./reference/weasyprint_guidelines.md`
+2. Critical CSS:
+   - `page-break-inside: avoid` on tables, boxes
+   - `page-break-after: avoid` on headings
+   - `orphans: 3; widows: 3` on paragraphs
+   - Use `display: table` not Flexbox/Grid
+   - Font sizes in pt (10pt body, 8pt citations)
+3. Generate: `weasyprint [html_path] [pdf_path]`
+4. Open: `open [pdf_path]`
+
+**Option B: generating-pdf Skill**
+
+Use Task tool with general-purpose agent, invoke generating-pdf skill.