Skip to content

Disentinel/grafema / .claude/skills/grafema-batch-plugin-development

grafema-batch-plugin-development

Verified

How to write a Grafema batch-mode plugin that reads the graph and filesystem, then writes new edges/nodes directly to RFDB. Use when: (1) need to add project-specific edges that generic analyzers can't produce, (2) need to read config files (JSON/YAML) and trace values into code, (3) implementing framework-specific resolvers (Django settings, Express routes, pipeline configs). Covers: grafema.config.yaml plugin config, RFDB field naming (src/dst NOT source/target), addEdges/addNodes API, RFDBServerBackend connection pattern.

Grafema Batch Plugin Development

Problem

Generic language analyzers (Python, JS, etc.) can't resolve project-specific patterns like config-driven registries, DI containers, or framework routing. Batch plugins bridge this gap by reading both the graph AND filesystem.

Context / Trigger Conditions

  • Need to resolve dynamic dependencies driven by config files (JSON, YAML)
  • Framework-specific patterns: importlib.import_module() + config, DI wiring, event dispatch, route→handler mapping
  • Generic analyzer produces the base graph, but project-specific edges are missing
  • User asks for "project-level plugin" or "config-driven resolution"

Solution

1. Plugin configuration in grafema.config.yaml

plugins:
  - name: my-project-plugin
    command: "node my-plugin.mjs"
    mode: batch  # KEY: batch mode gets RFDB_SOCKET env var

2. Plugin receives environment variables

RFDB_SOCKET=/path/to/.grafema/rfdb.sock
RFDB_DATABASE=default

3. Plugin template (Node.js / ESM)

const { RFDBServerBackend } = await import(
  '/path/to/grafema/packages/util/dist/storage/backends/RFDBServerBackend.js'
);

const backend = new RFDBServerBackend({
  socketPath: process.env.RFDB_SOCKET,
  autoStart: false,  // server already running
});
await backend.connect();

// Read existing graph
const allNodes = await backend.getAllNodes();

// Read project config files (filesystem access!)
import { readFileSync } from 'fs';
const config = JSON.parse(readFileSync('config.json', 'utf-8'));

// Build new edges
const newEdges = [];
// ... resolution logic ...

// CRITICAL: use src/dst, NOT source/target
newEdges.push({
  src: sourceNodeId,     // NOT 'source'
  dst: targetNodeId,     // NOT 'target'
  edgeType: 'MY_EDGE',  // NOT 'type' alone
  metadata: { ... },
});

// Write to RFDB
await backend.addEdges(newEdges);
await backend.flush();
await backend.close();

4. Critical field naming

CorrectWRONG (silent failure)What happens
srcsourceString(undefined) = "undefined" stored
dsttargetSame — edge created with garbage IDs
edgeTypetype onlyWorks but less explicit

As of v0.3.22+, validation throws with helpful hints:

addEdges: edge at index 0 is missing required 'src' field.
Did you mean 'src'? Found 'source' = 'grafema://...'

5. Orchestrator execution order

Analysis (parse files) → Resolution (python-resolve, etc.)
  → User plugins (your batch plugin runs HERE)
    → Unresolved diagnostics → Module dependency derivation → Metrics

Plugin runs AFTER built-in resolution, so it can read resolved edges.

Verification

After grafema analyze, check:

grafema overview --json | jq '.edgesByType'

New edge types from your plugin should appear.

Example: Pipeline Config Resolver

Resolves importlib.import_module(f".stages.{name}") + pipeline_config.json:

// Find importlib calls in graph
const importlibCalls = allNodes.filter(
  n => n.type === 'CALL' && n.name === 'import_module' && n.receiver === 'importlib'
);

// Read config
const stages = config.pipeline.stages.filter(s => s.enabled);

// For each configured stage, emit REGISTRY_WIRES edge
for (const call of importlibCalls) {
  for (const stage of stages) {
    const targetModule = allNodes.find(
      n => n.type === 'MODULE' && n.file === `pkg/stages/${stage.module}.py`
    );
    if (targetModule) {
      newEdges.push({
        src: call.id,
        dst: targetModule.id,
        edgeType: 'REGISTRY_WIRES',
        metadata: { mechanism: 'importlib', config_source: 'pipeline_config.json' },
      });
    }
  }
}

Notes

  • Batch plugins write directly to RFDB — orchestrator reports nodes=0 edges=0 in its log for batch plugins (this is expected, not a bug)
  • Plugin runs from the project root directory (where grafema.config.yaml lives)
  • Plugin stderr goes to orchestrator log; stdout is captured but ignored for batch mode
  • Use depends_on: ["python-resolution"] if your plugin needs resolved edges
  • getAllNodes() returns ALL nodes including METRIC/ISSUE — filter by type
  • Node IDs are URI format: grafema://host/file#TYPE-%3Ename%5Bscope%5D
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 319kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall