import{_ as o,C as i,o as s,c as r,a2 as a,b as l,w as n,a as p,E as c,a3 as d}from"./chunks/framework.CJEbdX1t.js";const k=JSON.parse('{"title":"Agent Mesh","description":"","frontmatter":{},"headers":[],"relativePath":"concepts/agent-mesh.md","filePath":"concepts/agent-mesh.md"}'),h={name:"concepts/agent-mesh.md"};function g(m,e,u,b,f,w){const t=i("Mermaid");return s(),r("div",null,[e[1]||(e[1]=a(`<h1 id="agent-mesh" tabindex="-1">Agent Mesh <a class="header-anchor" href="#agent-mesh" aria-label="Permalink to &quot;Agent Mesh&quot;">​</a></h1><p>Specwright&#39;s architecture is built in three tiers, from single-repo agents up to an organization-wide knowledge brain.</p><h2 id="three-tier-architecture" tabindex="-1">Three-Tier Architecture <a class="header-anchor" href="#three-tier-architecture" aria-label="Permalink to &quot;Three-Tier Architecture&quot;">​</a></h2><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>┌─────────────────────────────────────────────────┐</span></span>
<span class="line"><span>│              ORG BRAIN (Tier 3)                  │</span></span>
<span class="line"><span>│                                                  │</span></span>
<span class="line"><span>│  Knowledge graph · Cross-repo search · Patterns  │</span></span>
<span class="line"><span>│  &quot;Who owns payments?&quot; · &quot;What decided X?&quot;        │</span></span>
<span class="line"><span>│  Org-wide spec coverage · Dependency map          │</span></span>
<span class="line"><span>│  Executive dashboards · Compliance reports        │</span></span>
<span class="line"><span>├─────────────────────────────────────────────────┤</span></span>
<span class="line"><span>│              AGENT MESH (Tier 2)                 │</span></span>
<span class="line"><span>│                                                  │</span></span>
<span class="line"><span>│  Agent-to-agent communication · Event bus         │</span></span>
<span class="line"><span>│  &quot;Repo A&#39;s spec references Repo B&#39;s API&quot;         │</span></span>
<span class="line"><span>│  Cross-team impact analysis · Conflict detection  │</span></span>
<span class="line"><span>│  Shared vocabulary / taxonomy enforcement         │</span></span>
<span class="line"><span>├─────────────────────────────────────────────────┤</span></span>
<span class="line"><span>│              REPO AGENTS (Tier 1)                │</span></span>
<span class="line"><span>│                                                  │</span></span>
<span class="line"><span>│  All-markdown indexing · PR analysis · Doc PRs    │</span></span>
<span class="line"><span>│  Spec realization · Ticket sync · Stale detection │</span></span>
<span class="line"><span>│  MCP server · Slack Q&amp;A · Coverage metrics        │</span></span>
<span class="line"><span>│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐           │</span></span>
<span class="line"><span>│  │Repo 1│ │Repo 2│ │Repo 3│ │ ×300 │           │</span></span>
<span class="line"><span>│  └──────┘ └──────┘ └──────┘ └──────┘           │</span></span>
<span class="line"><span>└─────────────────────────────────────────────────┘</span></span></code></pre></div><p><strong>Tier 1</strong> is where you start. <strong>Tier 2</strong> is the moat. <strong>Tier 3</strong> is the platform.</p><h2 id="tier-1-repo-agents" tabindex="-1">Tier 1: Repo Agents <a class="header-anchor" href="#tier-1-repo-agents" aria-label="Permalink to &quot;Tier 1: Repo Agents&quot;">​</a></h2><p>Each repository gets its own agent that handles:</p><ul><li><strong>All-markdown indexing</strong> — Parses specs, ADRs, guides, READMEs into a searchable knowledge base</li><li><strong>PR analysis</strong> — Analyzes pull requests against spec acceptance criteria and indexed docs</li><li><strong>Spec realization</strong> — Verifies code implements what specs say, with evidence</li><li><strong>Doc-update PRs</strong> — Generates pull requests to update stale documentation</li><li><strong>Ticket sync</strong> — Bidirectional link between spec sections and Jira/Linear/GitHub Issues</li><li><strong>Stale detection</strong> — Flags docs that haven&#39;t been updated when related code changes</li><li><strong>MCP server</strong> — Exposes spec knowledge to coding agents (Claude Code, Cursor, VS Code)</li></ul><h3 id="analysis-pipeline" tabindex="-1">Analysis Pipeline <a class="header-anchor" href="#analysis-pipeline" aria-label="Permalink to &quot;Analysis Pipeline&quot;">​</a></h3><p>The PR analysis pipeline is the core workflow:</p>`,10)),(s(),l(d,null,{default:n(()=>[c(t,{id:"mermaid-62",class:"mermaid",graph:"flowchart%20TD%0A%20%20%20%20A%5Bpull_request%20webhook%5D%20--%3E%20B%7BConfig-only%20files%3F%7D%0A%20%20%20%20B%20--%20yes%20--%3E%20Z%5BSkip%20%E2%80%94%20no%20comment%5D%0A%20%20%20%20B%20--%20no%20--%3E%20C%5BLoad%20specs%20from%20base%20branch%5D%0A%20%20%20%20C%20--%3E%20D%7BSpecs%20found%3F%7D%0A%20%20%20%20D%20--%20no%20--%3E%20E%7BPR%20touches%20spec%20files%3F%7D%0A%20%20%20%20E%20--%20no%20--%3E%20Z%0A%20%20%20%20E%20--%20yes%20--%3E%20F%5BPost%20file-list%20comment%5D%0A%20%20%20%20D%20--%20yes%20--%3E%20G%5BRetrieve%20context%20docs%5D%0A%20%20%20%20G%20--%3E%20H%5BPost%20processing%20comment%5D%0A%20%20%20%20H%20--%3E%20I%5BBuild%20analysis%20context%5D%0A%20%20%20%20I%20--%3E%20J%5BCall%20Claude%5D%0A%20%20%20%20J%20--%3E%20K%5BParse%20JSON%20response%5D%0A%20%20%20%20K%20--%3E%20L%5BFormat%20comment%5D%0A%20%20%20%20L%20--%3E%20M%5BUpsert%20bot%20comment%5D%0A"})]),fallback:n(()=>[...e[0]||(e[0]=[p(" Loading... ",-1)])]),_:1})),e[2]||(e[2]=a(`<h3 id="interactive-commands" tabindex="-1">Interactive Commands <a class="header-anchor" href="#interactive-commands" aria-label="Permalink to &quot;Interactive Commands&quot;">​</a></h3><p>Users interact with the bot by commenting on PRs:</p><table tabindex="0"><thead><tr><th>Command</th><th>Behavior</th></tr></thead><tbody><tr><td><code>@specwright dismiss</code></td><td>Deletes the bot&#39;s analysis comment</td></tr><tr><td><code>@specwright reanalyze</code></td><td>Re-runs the full analysis pipeline</td></tr><tr><td><code>@specwright apply docs</code></td><td>Creates a PR with suggested doc updates applied</td></tr></tbody></table><h2 id="tier-2-agent-mesh" tabindex="-1">Tier 2: Agent Mesh <a class="header-anchor" href="#tier-2-agent-mesh" aria-label="Permalink to &quot;Tier 2: Agent Mesh&quot;">​</a></h2><div class="info custom-block"><p class="custom-block-title">Status: Planned</p><p>Tier 2 is on the roadmap. The features below describe the design vision.</p></div><p>When multiple repos have agents, the mesh layer enables cross-repo awareness:</p><ul><li><strong>Cross-repo references</strong> — Repo A&#39;s spec references Repo B&#39;s API; changes to B trigger analysis in A</li><li><strong>Impact analysis</strong> — A breaking change in a shared library flags all downstream specs</li><li><strong>Conflict detection</strong> — Two teams&#39; specs make contradictory assumptions about the same system</li><li><strong>Shared taxonomy</strong> — Enforce consistent terminology and patterns across the organization</li></ul><h2 id="tier-3-org-brain" tabindex="-1">Tier 3: Org Brain <a class="header-anchor" href="#tier-3-org-brain" aria-label="Permalink to &quot;Tier 3: Org Brain&quot;">​</a></h2><div class="info custom-block"><p class="custom-block-title">Status: Planned</p><p>Tier 3 is on the roadmap. The features below describe the design vision.</p></div><p>The org brain aggregates knowledge from all repo agents:</p><ul><li><strong>Cross-repo search</strong> — &quot;What does our retry policy look like across all services?&quot;</li><li><strong>Ownership graph</strong> — &quot;Who owns the payments domain?&quot;</li><li><strong>Decision index</strong> — &quot;What ADRs relate to database choices?&quot;</li><li><strong>Compliance reports</strong> — &quot;Which specs lack acceptance criteria?&quot;</li><li><strong>Executive dashboards</strong> — Organization-wide spec coverage and documentation health</li></ul><h2 id="the-network-effect" tabindex="-1">The Network Effect <a class="header-anchor" href="#the-network-effect" aria-label="Permalink to &quot;The Network Effect&quot;">​</a></h2><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>1 repo   → nice spec workflow, all docs searchable</span></span>
<span class="line"><span>10 repos → cross-repo references, shared knowledge base</span></span>
<span class="line"><span>50 repos → the agent mesh becomes indispensable</span></span>
<span class="line"><span>300 repos → the org brain knows more than any human</span></span>
<span class="line"><span>            about how the company&#39;s software works</span></span></code></pre></div><p>Each new repo makes every existing repo&#39;s agent smarter. Each indexed doc enriches the knowledge base. Each PR analysis teaches the platform what changed.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><strong>Guide</strong>: <a href="/docs/guides/self-hosting.html">Self-Hosting</a> — deploy Specwright on your own K8s cluster</li><li><strong>Guide</strong>: <a href="/docs/guides/ci-integration.html">CI Integration</a> — run <code>specwright verify</code> in your CI pipeline</li><li><strong>Reference</strong>: <a href="/docs/reference/mcp.html">MCP Tools</a> — the 11 tools exposed to coding agents</li><li><strong>Reference</strong>: <a href="/docs/reference/skills.html">Claude Code Skills</a> — <code>/sw:*</code> commands for interactive agent workflows</li><li><strong>Architecture</strong>: <a href="/docs/architecture/system-design.html">System Design</a> — component diagram and deployment architecture</li><li><strong>Architecture</strong>: <a href="/docs/architecture/data-flow.html">Data Flow</a> — PR analysis and ticket sync request flows</li></ul>`,16))])}const A=o(h,[["render",g]]);export{k as __pageData,A as default};
