{
  "markdown": "# distributed-architect\r\n\r\nA reasoning framework plugin for [Claude Code](https://claude.ai/code) that helps LLMs catch distributed system bugs before they reach production.\r\n\r\n## The Problem\r\n\r\nLLMs reason about code **locally** — they read a function, understand its logic, and suggest changes that are locally correct. Distributed systems require **globally correct** changes: every state mutation must be valid from every observer's perspective, including under partial failure.\r\n\r\nThis gap produces specific, recurring mistakes:\r\n- Setting a service to \"idle\" without checking if the system will immediately re-dispatch to the same broken instance (tight retry loops)\r\n- Assuming a monitoring channel failure means the operation failed (channel conflation)\r\n- Losing data at acknowledgment boundaries because the only copy was in the queue\r\n- Missing feedback loops that span multiple components\r\n\r\nThese aren't knowledge gaps — they're reasoning gaps. The LLM knows about distributed systems. It just doesn't systematically apply that knowledge at the moment of writing code.\r\n\r\n## How It Works\r\n\r\n**Three layers, loaded incrementally to minimize context cost:**\r\n\r\n| Layer | What | When Loaded | Context Cost |\r\n|-------|------|-------------|-------------|\r\n| Boundary Signal Reference | Recognizes when a change crosses a distributed boundary | `@`-imported into a project's `CLAUDE.md` (opt-in), or read directly by the skills | Near zero |\r\n| Reasoning Modules | Checklists for specific concern types (5 modules) | On signal detection | ~50 lines each |\r\n| Anti-Pattern Catalog | Named patterns with shape/detection/fix | Review or debug mode | ~10 lines each |\r\n\r\n**Two-pass analysis at coding time:**\r\n1. **Boundary correctness** — Does this single operation work correctly across components?\r\n2. **Concurrency correctness** — Do simultaneous operations conflict? (Triggered by project topology)\r\n\r\n**Three entry points for different phases:**\r\n- `/dist-check` — Coding time: verify changes before committing\r\n- `/dist-design` — Design time: evaluate architecture trade-offs\r\n- `/dist-debug` — Debug time: trace symptoms backward to root cause\r\n\r\n## Project Topology\r\n\r\nEach project creates a lightweight topology file that captures component relationships and cardinality. This drives analysis decisions:\r\n\r\n```yaml\r\ntopology:\r\n  - from: api-gateway\r\n    count: 1 (fixed)\r\n    to: task-runner\r\n    count: N (dynamic)\r\n    via: message queue\r\n    notes: \"1:N — concurrency on the gateway side\"\r\n\r\n  - from: task-runner\r\n    count: 1 (fixed)\r\n    to: execution-backend\r\n    count: 1 (fixed, per-runner)\r\n    via: HTTP + event stream\r\n    notes: \"1:1 tight coupling\"\r\n```\r\n\r\nCardinality determines which analysis is triggered:\r\n- **1:N** — Concurrency analysis mandatory on the \"1\" side\r\n- **1:1** — Failure cascade analysis\r\n- **N:1** — Bottleneck / SPOF analysis\r\n\r\n## Anti-Pattern Catalog\r\n\r\nSix patterns identified from real debugging sessions, with more added over time:\r\n\r\n| Pattern | Shape |\r\n|---------|-------|\r\n| Tight Retry Loop | Error handler sets state to \"ready\" -> system immediately retries -> same error |\r\n| Lost Data at ACK | Data only in queue -> consumer ACKs -> data gone -> needed later |\r\n| Channel Conflation | Monitoring channel drops -> assume the monitored operation failed |\r\n| Boundary State Leak | Component exposes internal state across its interface |\r\n| Compounding Retry | Multiple retry layers multiply into retry storms |\r\n| Premature State Transition | Advertise new state before preconditions are verified |\r\n\r\n## Usage\r\n\r\nLoad as a Claude Code plugin:\r\n\r\n```bash\r\nclaude --plugin-dir /path/to/distributed-architect\r\n```\r\n\r\nSkills are registered as `/distributed-architect:dist-check`, etc. Use them during your work:\r\n- `/distributed-architect:dist-check` before committing distributed system changes\r\n- `/distributed-architect:dist-design` when evaluating architecture options\r\n- `/distributed-architect:dist-debug` when investigating cross-component failures\r\n\r\nClaude Code doesn't load an installed plugin's `CLAUDE.md` into every session, so passive detection isn't automatic. For a project where you want the boundary-signal table always active, `@`-import it from this plugin's `CLAUDE.md` into that project's own `CLAUDE.md`.\r\n\r\n## Design Philosophy\r\n\r\nThis is a **reasoning coach, not a knowledge base**. It doesn't try to document your system — it teaches the LLM what questions to ask at the right moment. Documents go stale; reasoning patterns don't.\r\n\r\nSee `docs/design-philosophy.md` for the full rationale.\r\n\r\n## Structure\r\n\r\n```\r\ndistributed-architect/\r\n├── .claude-plugin/\r\n│   └── plugin.json        # Plugin manifest\r\n├── CLAUDE.md              # Plugin instructions + boundary-signal reference (not auto-loaded — see Usage)\r\n├── modules/               # Layer 2: reasoning checklists (loaded on demand)\r\n│   ├── state-mutation.md\r\n│   ├── data-lifecycle.md\r\n│   ├── failure-mode.md\r\n│   ├── interaction.md\r\n│   └── concurrency.md\r\n├── catalog/               # Layer 3: anti-pattern reference\r\n│   ├── _drafts/           # Auto-captured, pending promotion\r\n│   └── *.md               # Promoted patterns\r\n├── skills/                # Registered skills (SKILL.md per skill)\r\n│   ├── dist-check/\r\n│   │   └── SKILL.md\r\n│   ├── dist-design/\r\n│   │   └── SKILL.md\r\n│   └── dist-debug/\r\n│       └── SKILL.md\r\n├── templates/\r\n│   └── topology.yaml      # Project topology template\r\n└── docs/                  # Design documents & case studies\r\n```\r\n",
  "bytes": 5512,
  "sha": "d9d4b022d821658578ba8098f6f447e5cb9648617bd341592684c3c95c1b1460",
  "repo_slug": "langerrr/distributed-architect",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_langerrr_distributed_architect_distribut_b793da2b/readme"
}