{
  "markdown": "# Ergo Framework Claude Code Integration\n\nClaude Code agents and skills for building and operating distributed actor-based systems with Ergo Framework (v3.3+).\n\nTwo complementary pairs:\n\n- **framework** - designing and implementing actor systems (build-time).\n- **devops** - diagnosing running clusters through the observer's MCP surface (runtime).\n\nEach pair is split into an **agent** (behaviour / policy / decision logic) and a **skill** (compact reference data, API surface, playbooks). The agent is slim and decides *what to do*; the skill is loaded progressively and answers *what the code actually says*.\n\n## Contents\n\n```\nclaude/\n├── .claude-plugin/\n│   ├── plugin.json\n│   └── marketplace.json\n├── agents/\n│   ├── framework-architect.md\n│   └── devops.md\n└── skills/\n    ├── framework/\n    │   ├── SKILL.md                       # navigation + critical rules\n    │   └── references/\n    │       ├── actors.md                  # lifecycle, mailbox, Link/Monitor, Alias, Events, CoreEvent\n    │       ├── supervision.md             # types, strategies, intensity, per-child restart, dynamic\n    │       ├── messages.md                # Send/Call, important delivery, priority, compression\n    │       ├── application.md             # embed app.Application, Load(args), lifecycle, helper API\n    │       ├── pool.md                    # Pool, act.Router, act.WebWorker\n    │       ├── meta.md                    # TCP/UDP/Web/Port, ProcessPool routing\n    │       ├── node.md                    # NodeOptions, NetworkFlags, Security, CertManager/TLS\n    │       ├── edf.md                     # Network().RegisterType, schema evolution, visibility\n    │       ├── cluster.md                 # etcd/Saturn, Registrar, ResolveApplication, proxy\n    │       ├── tracing.md                 # samplers, business spans, exporters, TracingFlags\n    │       ├── cron.md                    # gen.Cron, CronJob, cron actions, MessageCron\n    │       ├── logging.md                 # gen.Log, LogLevel, structured fields, LoggerBehavior\n    │       ├── errors.md                  # gen sentinels, TerminateReason*, errors.Is\n    │       ├── testing.md                 # unit/stage/check/mock: Spawn, Should*, injection\n    │       ├── actor-lib.md               # actor/health, leader, metrics\n    │       ├── applications-lib.md        # application/observer, pulse, radar\n    │       ├── meta-lib.md                # meta/websocket, meta/sse\n    │       ├── integrations.md            # registrar/etcd, saturn, logger/colored, rotate, sentry\n    │       └── erlang-protocol.md         # proto/erlang23 (EPMD, ETF, DIST)\n    └── devops/\n        ├── SKILL.md                       # navigation + critical rules\n        └── references/\n            ├── tools.md                   # the surface: URI grammar, lenses, tools, arguments\n            ├── process-model.md           # states, mailbox, liveness formula\n            ├── counters.md                # every counter of every reading, with meanings\n            ├── framework-internals.md     # Important errors, restart intensity, pool, fanout\n            ├── playbooks.md               # diagnostic playbooks, symptom by symptom\n            ├── watching.md                # accumulating lenses, keyed watches, runs, samplers\n            └── build-tags.md              # pprof, latency, verbose, norecover, typestats\n```\n\n## How the Split Works\n\n**Agents** (~6 KB each) carry only behavioural rules: trigger cues, diagnostic approach, decision tables, anti-patterns, permission rules. They contain no API signatures.\n\n**Skills** use progressive disclosure - the top-level `SKILL.md` is a small (~3 KB) index with a navigation table plus the five non-negotiable rules. Concrete API details, tool schemas, formulas, and playbooks live in `references/*.md`, each ~150-500 lines and loaded on demand.\n\nA typical task loads:\n1. `SKILL.md` (auto) - ~3 KB.\n2. One or two relevant `references/*.md` - ~5-10 KB.\n\nTotal working-set ≈ 8-13 KB vs ~17 KB monolithic; detail per topic is higher rather than lower.\n\n## Pair Comparison\n\n| | framework | devops |\n|--|---|---|\n| **Purpose** | Design and implement actor systems | Diagnose running clusters |\n| **Invoked when** | Designing an actor architecture, writing a test, choosing a supervisor strategy | Investigating a production issue, reading counters, running `pprof` |\n| **Style** | Design doc format + concrete code patterns | Hypothesis-driven investigation + MCP commands |\n| **Requires** | Ergo Framework v3.3+ source or module cache | `application/observer` on one node of the cluster |\n\n## Installation\n\n### Easiest: from the Claude Code plugin marketplace\n\nThe plugin is already published in the Claude Code marketplace. In Claude Code, open the plugins section (run `/plugin`), search for `ergo`, and install it - no manual setup required.\n\n### From the source repo\n\nAdd this repository as a marketplace and install; updates are handled by Claude Code:\n\n```bash\n/plugin marketplace add ergo-services/claude\n/plugin install ergo@ergo-services\n```\n\nAfter install, agents and skills are namespaced under the plugin - invoke skills as `/ergo:framework` / `/ergo:devops`; agents pick themselves up from trigger phrases.\n\nUpdate later with `/plugin update`, remove with `/plugin uninstall ergo@ergo-services`.\n\n### Manual (development / fork / offline)\n\nIf you are editing the agents and skills locally, or running without network access, link or copy the files directly.\n\n#### Symlink into `~/.claude`\n\n```bash\ncd path/to/ergo.services/claude\n\nmkdir -p ~/.claude/agents ~/.claude/skills\n\n# Agents\nln -sf $(pwd)/agents/framework-architect.md ~/.claude/agents/\nln -sf $(pwd)/agents/devops.md              ~/.claude/agents/\n\n# Skills (directories - references/ is picked up transitively)\nln -sf $(pwd)/skills/framework ~/.claude/skills/\nln -sf $(pwd)/skills/devops    ~/.claude/skills/\n```\n\n#### Copy\n\n```bash\ncp -r agents/* ~/.claude/agents/\ncp -r skills/* ~/.claude/skills/\n```\n\n## Usage\n\n### framework-architect (Agent)\n\nDesigns Ergo Framework applications with DDD bounded contexts, supervision trees, and cluster topology. Outputs an implementable design document.\n\n**Trigger phrases**\n- \"design ergo application\"\n- \"ergo architecture\"\n- \"create ergo design document\"\n- \"actor system design\"\n\n**Output** - a design document with bounded context, cluster topology, supervision tree, data structures, message flow, load analysis, and implementation phases.\n\n### devops (Agent)\n\nConnects to a running cluster through the observer's MCP surface and runs hypothesis-driven investigations. Never mutates state without explicit user permission.\n\n**Trigger phrases**\n- \"why is it slow\"\n- \"find process leak\"\n- \"check cluster health\"\n- \"debug this node\"\n- \"monitor for anomalies\"\n\n**Capabilities**\n- Performance bottleneck investigation (mailbox depth, latency, drain ratio, liveness score).\n- Process leak and zombie detection.\n- Restart loop analysis.\n- Memory growth investigation (heap profiling, GC pressure).\n- Network connectivity and traffic analysis (both sides of every connection).\n- Event / pub-sub diagnostics (fanout, publishing-to-void, starved subscribers).\n- Goroutine debugging (deadlocks, leaks, per-process stack traces).\n- Watching over time: accumulating lenses read with a cursor, keyed watches, subscriptions.\n- Cluster-wide queries as runs: one question put to many nodes at once.\n\n**Requires** - `ergo.services/application/observer` on one node. The nodes it inspects need nothing: they already run the built-in `system` application it asks.\n\n### framework (Skill)\n\nReference for implementing Ergo Framework applications. Load via `/ergo:framework` or automatically when the topic matches. Follow the navigation table in `SKILL.md` to pull in only the needed `references/*.md`.\n\n### devops (Skill)\n\nReference for diagnosing live Ergo nodes. Load via `/ergo:devops`. Navigation table lists 7 topic files - the surface catalog, process model, counters, watching over time, playbooks, framework internals, build tags.\n\n## MCP Surface Setup\n\nThe `devops` pair works through the MCP surface of the Observer application:\n\n```go\nimport \"ergo.services/application/observer\"\n\nnode, _ := ergo.StartNode(\"mynode@host\", gen.NodeOptions{\n    Applications: []gen.ApplicationBehavior{\n        observer.CreateApp(observer.Options{\n            Port:    9911,                              // default; serves UI, API and MCP\n            Ceiling: observer.Ceiling{ReadOnly: true},  // production: refuse the manage. plane\n        }),\n    },\n})\n```\n\nConnect from Claude Code:\n\n```bash\nclaude mcp add --transport http ergo http://localhost:9911/mcp\n# or through a proxy that authenticates the caller:\nclaude mcp add --transport http ergo http://localhost:9911/mcp \\\n    --header \"Authorization: Bearer ${TOKEN}\"\n```\n\nReadings are resources addressed as `ergo://<node>/<lens>`, and every tool takes a `node` argument. Both take the node name from `ergo://cluster`, which is where an investigation starts. The node serving MCP holds no privileged position: name the target explicitly, including that one.\n\n## Build Tags for Better Diagnostics\n\n| Tag | Effect |\n|-----|--------|\n| `-tags=pprof` | Per-process goroutine labels + pprof HTTP server at `localhost:9009` |\n| `-tags=latency` | Enables `MailboxLatency` measurement (required for liveness score) |\n| `-tags=verbose` | Verbose framework-internal logging |\n| `-tags=norecover` | **Disables** panic recovery (debug only) |\n| `-tags=typestats` | Per-type EDF encode/decode counters (`gen.RegisteredTypeStats`) |\n\nSee `skills/devops/references/build-tags.md` for detail.\n\n## Reference\n\nWhen a signature or constant must be exact, verify against the framework source:\n\n```bash\nls $(go env GOMODCACHE)/ergo.services/ergo@*/version.go\nls $(go env GOMODCACHE)/ergo.services/ergo@*/docs/\n```\n\n## Requirements\n\n- Claude Code CLI\n- Ergo Framework v3.3+\n- For `devops`: `ergo.services/application/observer` on one node, which reaches the rest of the cluster\n",
  "bytes": 9992,
  "sha": "05a212e0fed89d0c9c92035be96d902bb76f5729c32060156f35201bcddb4658",
  "repo_slug": "ergo-services/claude",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_ergo_services_claude_ergo_5c98089d/readme"
}