agentopology 0.2.4 → 0.3.0

package/examples/company-brain-team.at

@@ -0,0 +1,241 @@
+# company-brain-team.at — A team of agents that build & maintain a company brain
+#
+# The flagship "company brain" topology. A folder of Obsidian-format markdown,
+# fed and maintained by a TEAM — not one librarian:
+#
+#   📧 gmail-ingester    ─┐
+#   💬 slack-ingester    ─┼─► drop raw notes into brain/    ─► 👤 librarian wires them
+#   📅 calendar-ingester ─┘    (each owns ONE source)          (links, tags, hubs)
+#                                                              ─► 🔍 auditor heals the graph
+#
+# - Ingesters are scheduled — they pull from their source and write raw markdown.
+# - The librarian is custodian-of the brain: it wires dropped notes into the graph.
+# - The auditor is custodian-of the brain too: it heals broken links, surfaces
+#   ghost nodes, and flags duplicates.
+# - A researcher reads the brain to answer questions.
+#
+# This is the whitespace: declarative + multi-agent team + Obsidian-portable +
+# agents own memory layers. Demonstrates `brain` + `custodian-of` + ingestion.
+
+topology company-brain-team : [brain, event-driven, human-gate] {
+
+  meta {
+    version: "0.1.0"
+    description: "A team of agents that ingest, wire, and maintain a company brain"
+  }
+
+  # --- The brain: one Obsidian-format markdown vault, no database ---
+
+  memory {
+    store brain {
+      type: brain
+      description: "The company brain — fed by ingesters, wired by the librarian"
+      path: "brain/"
+      format: obsidian
+      scope: org
+
+      # Presentation only — colors/icons for the graph view, by provenance.
+      # A note's `source:` frontmatter (stamped by its ingester) maps to a look.
+      # Cosmetic: bindings ignore this; delete it and the brain works the same.
+      sources {
+        gmail {
+          color: "#EA4335"
+          icon: "./logos/gmail.svg"
+        }
+        slack {
+          color: "#4A154B"
+          icon: "./logos/slack.svg"
+        }
+        calendar {
+          color: "#4285F4"
+        }
+      }
+    }
+  }
+
+  # --- Ingesters: each owns ONE external source, writes raw notes ---
+
+  agent gmail-ingester {
+    model: sonnet
+    description: "Pulls notable emails and writes them as raw notes into the brain"
+    tools: [Read, Write, Grep, Glob]
+    mcp-servers: [gmail]
+    writes: ["brain/"]
+
+    prompt {
+        You ingest email into the brain. On each run:
+        - Pull recent notable threads (decisions, deals, intros, commitments).
+        - For each, write ONE raw markdown note into `brain/` with a clear title
+          and YAML frontmatter (date, source: gmail, participants).
+        - Do NOT wire links or tags — that is the librarian's job. Just capture
+          the content faithfully. Skip noise (newsletters, automated mail).
+    }
+  }
+
+  agent slack-ingester {
+    model: sonnet
+    description: "Captures key Slack decisions and threads as raw notes"
+    tools: [Read, Write, Grep, Glob]
+    mcp-servers: [slack]
+    writes: ["brain/"]
+
+    prompt {
+        You ingest Slack into the brain. On each run, capture threads where a
+        decision was made, a commitment given, or knowledge shared. Write each
+        as ONE raw markdown note in `brain/` with frontmatter (date, source:
+        slack, channel). Leave linking and tagging to the librarian.
+    }
+  }
+
+  agent calendar-ingester {
+    model: sonnet
+    description: "Turns meetings into raw notes (attendees, outcomes)"
+    tools: [Read, Write, Grep, Glob]
+    mcp-servers: [calendar]
+    writes: ["brain/"]
+
+    prompt {
+        You ingest calendar events into the brain. For meetings that mattered,
+        write ONE raw markdown note in `brain/` with frontmatter (date, source:
+        calendar, attendees) and any outcomes/notes you can infer. No linking —
+        that is the librarian's job.
+    }
+  }
+
+  # --- Librarian: custodian that WIRES dropped notes into the graph ---
+
+  agent librarian {
+    model: sonnet
+    description: "Wires raw notes into the brain graph — links, tags, hubs"
+    tools: [Read, Write, Edit, Grep, Glob]
+
+    custodian-of: [brain] {
+      does: [link, tag, index, dedupe]
+    }
+
+    prompt {
+        You are the brain's librarian. Raw notes arrive from the ingesters and
+        from humans. You never invent content — you wire what is dropped in.
+        Resolve mentions into [[wikilinks]], assign #nested/tags, keep the hub
+        notes current, and flag duplicates. Leave ghost links to mark gaps.
+    }
+  }
+
+  # --- Auditor: custodian that keeps the whole graph HEALTHY ---
+
+  agent auditor {
+    model: opus
+    description: "Heals the brain — broken links, ghost nodes, orphans, dupes"
+    tools: [Read, Edit, Grep, Glob]
+
+    custodian-of: [brain] {
+      does: [heal, dedupe, index]
+    }
+
+    prompt {
+        You audit the brain's health. Find and repair broken [[links]] after
+        renames, surface ghost nodes (links to notes that don't exist), flag
+        orphan notes (nothing links to them), and propose merges for duplicates.
+        Conservative: repair links and report issues — never delete a human's note.
+    }
+  }
+
+  # --- Researcher: READS the brain to answer questions ---
+
+  agent researcher {
+    model: sonnet
+    description: "Answers questions by traversing the brain"
+    tools: [Read, Grep, Glob]
+    memory: [brain]
+
+    prompt {
+        Answer questions using only the brain in `brain/`. Grep for relevant
+        notes, follow their [[wikilinks]] and #tags, and cite notes by filename.
+    }
+  }
+
+  # --- Actions (flow entry/exit points) ---
+
+  action wire-in {
+    kind: inline
+    description: "Fold a dropped or freshly-ingested note into the brain"
+  }
+
+  action audit {
+    kind: report
+    description: "Report the brain's health: ghosts, orphans, broken links, dupes"
+  }
+
+  action query {
+    kind: inline
+    description: "Ask the brain a question"
+  }
+
+  # --- Flow: ingesters feed the librarian; auditor runs after; researcher reads ---
+
+  flow {
+    gmail-ingester    -> wire-in
+    slack-ingester    -> wire-in
+    calendar-ingester -> wire-in
+    wire-in           -> librarian
+    librarian         -> auditor
+    auditor           -> audit
+    query             -> researcher
+  }
+
+  # --- Schedule: ingesters and the auditor run on their own cadence ---
+
+  schedule {
+    job pull-email {
+      cron: "0 */2 * * *"
+      agent: gmail-ingester
+    }
+    job pull-slack {
+      cron: "0 */2 * * *"
+      agent: slack-ingester
+    }
+    job pull-calendar {
+      cron: "0 8 * * *"
+      agent: calendar-ingester
+    }
+    job nightly-audit {
+      cron: "0 3 * * *"
+      agent: auditor
+    }
+  }
+
+  # --- Triggers: humans can wire a file or ask the brain anytime ---
+
+  triggers {
+    command wire-in {
+      pattern: "/wire-in <FILE>"
+      argument: FILE
+      description: "Fold a dropped markdown file into the brain"
+    }
+    command query {
+      pattern: "/ask <QUESTION>"
+      argument: QUESTION
+      description: "Ask the brain a question"
+    }
+  }
+
+  # --- External sources the ingesters connect to ---
+
+  mcp-servers {
+    gmail {
+      type: stdio
+      command: "npx"
+      args: ["-y", "gmail-mcp-server"]
+    }
+    slack {
+      type: stdio
+      command: "npx"
+      args: ["-y", "slack-mcp-server"]
+    }
+    calendar {
+      type: stdio
+      command: "npx"
+      args: ["-y", "calendar-mcp-server"]
+    }
+  }
+}

package/examples/company-brain.at

@@ -0,0 +1,104 @@
+# company-brain.at — A plug-and-play company brain
+#
+# A folder of Obsidian-format markdown, maintained by agents, not by hand.
+# - Humans drop a new note and run /wire-in. The librarian links & tags it.
+# - The researcher traverses the [[link]] graph (with grep) to answer questions.
+# - No vector DB, no MCP server. The brain is a folder you can git clone and
+#   open in Obsidian for the graph view.
+#
+# Demonstrates the `brain` PATTERN + the `custodian-of` PRIMITIVE.
+
+topology company-brain : [brain, human-gate] {
+
+  meta {
+    version: "0.1.0"
+    description: "An agent-maintained, Obsidian-portable company brain"
+  }
+
+  # --- The brain itself: one markdown store, no backend ---
+
+  memory {
+    store brain {
+      type: brain                 # NEW store type — no DB, just files
+      description: "The company brain — a folder of linked markdown"
+      path: "brain/"              # this folder IS a valid Obsidian vault
+      format: obsidian            # [[wikilinks]], #nested/tags, YAML frontmatter
+      scope: org
+    }
+  }
+
+  # --- The librarian: KEEPER of the brain (the new primitive) ---
+
+  agent librarian {
+    model: sonnet
+    description: "Maintains the brain — wires new notes into the graph"
+    tools: [Read, Write, Edit, Grep, Glob]
+
+    custodian-of: [brain] {       # owns upkeep, not just read access
+      does: [link, tag, index, dedupe]   # OPTIONAL verbs — visible strategy
+    }
+
+    prompt {
+        You are the brain's librarian. The brain lives in `brain/` as Obsidian
+        markdown. You never invent content — you wire what's dropped in.
+
+        When a note is added or changed:
+        - link:   find mentions of existing notes and turn them into [[wikilinks]]
+        - tag:    add #nested/tags consistent with the existing tag hierarchy
+        - index:  update the relevant hub note (a Map-of-Content that [[links]]
+                  the cluster) so the new note is reachable
+        - dedupe: flag near-duplicate notes for human review; never auto-delete
+
+        Backlinks are computed from the [[links]] you write — never author them
+        by hand. If a note links to something that doesn't exist yet, leave the
+        ghost link; it marks a gap to fill later.
+    }
+  }
+
+  # --- The researcher: READS the brain to answer questions ---
+
+  agent researcher {
+    model: sonnet
+    description: "Answers questions by traversing the brain"
+    tools: [Read, Grep, Glob]
+    memory: [brain]               # read access — the ordinary wiring
+
+    prompt {
+        Answer questions using only the brain in `brain/`. Start by grepping for
+        relevant notes, then follow their [[wikilinks]] and #tags to gather the
+        full picture. Cite the notes you used by filename.
+    }
+  }
+
+  # --- What the human can do (actions are the flow entry points) ---
+
+  action wire-in {
+    kind: inline
+    description: "Fold a dropped markdown file into the brain"
+  }
+
+  action query {
+    kind: inline
+    description: "Ask the brain a question"
+  }
+
+  triggers {
+    command wire-in {
+      pattern: "/wire-in <FILE>"
+      argument: FILE
+      description: "Fold a dropped markdown file into the brain"
+    }
+    command query {
+      pattern: "/ask <QUESTION>"
+      argument: QUESTION
+      description: "Ask the brain a question"
+    }
+  }
+
+  # --- Flow ---
+
+  flow {
+    wire-in -> librarian          # human drops a file → librarian wires it
+    query   -> researcher         # human asks → researcher traverses & answers
+  }
+}

package/examples/logos/gmail.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="48" height="48"><path fill="#fff" d="M6 12h36v26H6z"/><path fill="#EA4335" d="M6 14v3l18 12L42 17v-3l-18 12z"/><path fill="#FBBC04" d="M6 14v22h6V18l12 8 12-8v18h6V14l-18 12z" opacity=".9"/><path fill="#34A853" d="M6 36h6V18l-6-4z"/><path fill="#4285F4" d="M42 36h-6V18l6-4z"/><path fill="#C5221F" d="M6 14l18 12L42 14v-2H6z"/></svg>

package/examples/logos/slack.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="48" height="48"><path fill="#36C5F0" d="M18 6a4 4 0 100 8h4V10a4 4 0 00-4-4z"/><path fill="#2EB67D" d="M42 18a4 4 0 10-8 0v4h4a4 4 0 004-4z"/><path fill="#ECB22E" d="M30 42a4 4 0 100-8h-4v4a4 4 0 004 4z"/><path fill="#E01E5A" d="M6 30a4 4 0 108 0v-4h-4a4 4 0 00-4 4z"/><path fill="#36C5F0" d="M18 18h8v8h-8z" opacity=".7"/></svg>

package/examples/matchmat-ship.at

@@ -0,0 +1,249 @@
+# matchmat-ship.at — MatchMat autonomous ship-harness (HYBRID host + embedded workflow)
+#
+# The declarative source of truth for MatchMat's fast ship pipeline. Compiles via
+# a DUAL emitter: claude-code (the HOST — roles, flow, hooks, Blackboard) + the
+# claude-workflow binding (the BUILD phase → an embedded workflow.js for
+# deterministic parallel fan-out). They couple through the Blackboard (workspace
+# files; see memory.workspace + each agent's reads/writes).
+#
+# Methodology: contract-driven development + closed-loop regression. NO TDD.
+# Autonomous up to the HUMAN promote boundary; regression is a downstream workflow.
+#
+# Seam marking: agents that should compile to the embedded deterministic Workflow
+# carry `extensions { claude-workflow { execution: workflow } }`. Everything else
+# stays on the host session (hooks/gates/branching/observability).
+
+topology matchmat-ship : [pipeline, fan-out, blackboard, human-gate] {
+
+  meta {
+    version: "1.1.0"
+    description: "Hybrid ship pipeline: contract-research fan-out (host) -> parallel build in worktrees (embedded workflow) -> adversarial verify (host) -> human promote. Blackboard couples the layers. Regression is downstream."
+    domain: devops
+  }
+
+  providers {
+    anthropic {
+      api-key: "${ANTHROPIC_API_KEY}"
+      models: [opus, sonnet]
+      default: true
+    }
+  }
+
+  orchestrator {
+    model: opus
+    handles: [intake, ship-report]
+  }
+
+  roles {
+    contract-scout: "Find existing contracts/boundaries the ticket touches"
+    blast-radius-mapper: "Map the files and components the change affects"
+    boundary-drafter: "Draft the new boundaries/contracts the change requires"
+    builder: "Implement against the contract delta in an isolated worktree (no TDD); also write the paired regression spec"
+    security-verifier: "Adversarially scan the diff for security red flags"
+    contract-verifier: "Verify the code honors the contract invariants it claims (no drift)"
+    closed-loop-verifier: "Verify a paired regression spec exists and asserts in contract vocabulary"
+  }
+
+  # --- Actions ---
+
+  action intake {
+    kind: external
+    source: "trello"
+    description: "Fetch the Trello ticket and seed the Blackboard (workspace/ticket.md)"
+  }
+
+  action ship-report {
+    kind: report
+    description: "Compile contract delta, build summary, and verify verdicts for the human"
+  }
+
+  # --- Phase 1: CONTRACT RESEARCH (host fan-out) ---
+  # Stays on the host: reads/writes the Blackboard; observability hooks watch it.
+
+  agent contract-scout {
+    role: contract-scout
+    model: sonnet
+    permissions: supervised
+    phase: 1
+    prompt {
+      Find every existing contract (contracts/C-*.yaml) and boundary
+      (contracts/B-*.yaml) the ticket touches. List each with the invariant
+      at stake. Write findings to the Blackboard.
+    }
+    tools: [Read, Grep, Glob, Write]
+    reads: ["workspace/ticket.md"]
+    writes: ["workspace/contracts-touched.md"]
+  }
+
+  agent blast-radius-mapper {
+    role: blast-radius-mapper
+    model: sonnet
+    permissions: supervised
+    phase: 1
+    prompt {
+      Map the blast radius: which src/ files, edge functions, migrations, and
+      components the change affects. Produce an ordered file list with rationale.
+    }
+    tools: [Read, Grep, Glob, Write]
+    reads: ["workspace/ticket.md"]
+    writes: ["workspace/blast-radius.md"]
+  }
+
+  agent boundary-drafter {
+    role: boundary-drafter
+    model: opus
+    permissions: supervised
+    phase: 1
+    prompt {
+      Draft the NEW boundaries/contracts the change requires (or version bumps
+      to existing ones). Output the exact contract delta the build phase will
+      implement against.
+    }
+    tools: [Read, Grep, Glob, Write]
+    reads: ["workspace/ticket.md"]
+    writes: ["workspace/contract-delta.md"]
+  }
+
+  # --- Phase 2: BUILD (embedded WORKFLOW — deterministic parallel fan-out) ---
+  # execution: workflow → this phase compiles to an embedded workflow.js. Agents
+  # run in parallel worktrees, read the Blackboard (contract delta + blast radius),
+  # write build results back to the Blackboard so host hooks observe progress.
+
+  agent builder {
+    role: builder
+    model: opus
+    permissions: autonomous
+    phase: 2
+    isolation: worktree
+    prompt {
+      Implement your assigned slice of the contract delta in an isolated git
+      worktree. Code against the contract as the spec (NO TDD). In the SAME
+      change, write or extend the paired regression spec under e2e/walkthroughs/
+      in contract vocabulary. Touch the contract YAML if it evolves. Write a
+      build report to the Blackboard.
+    }
+    tools: [Read, Grep, Glob, Write, Edit, Bash]
+    reads: ["workspace/contract-delta.md", "workspace/blast-radius.md", "workspace/contracts-touched.md"]
+    writes: ["workspace/build-report.md"]
+    scale {
+      mode: auto
+      by: source-count
+      min: 1
+      max: 6
+    }
+    extensions {
+      claude-workflow {
+        execution: workflow
+      }
+    }
+  }
+
+  # --- Phase 3: ADVERSARIAL VERIFY (host fan-out) ---
+
+  agent security-verifier {
+    role: security-verifier
+    model: opus
+    permissions: supervised
+    phase: 3
+    prompt {
+      Adversarially scan the diff for red flags: hardcoded secrets, RLS holes,
+      SQL string concat, missing role checks, service-role key in client code.
+      Default to fail if uncertain.
+    }
+    tools: [Read, Grep, Glob, Bash]
+    reads: ["workspace/build-report.md"]
+    writes: ["workspace/verify-security.md"]
+    outputs: {
+      verdict: pass | fail
+    }
+  }
+
+  agent contract-verifier {
+    role: contract-verifier
+    model: sonnet
+    permissions: supervised
+    phase: 3
+    prompt {
+      Verify the code honors the contract invariants it claims. Check for drift
+      between implemented behavior and the contract/boundary YAML. Default to
+      fail if the code diverges from a declared invariant.
+    }
+    tools: [Read, Grep, Glob]
+    reads: ["workspace/build-report.md", "workspace/contract-delta.md"]
+    writes: ["workspace/verify-contract.md"]
+    outputs: {
+      verdict: pass | fail
+    }
+  }
+
+  agent closed-loop-verifier {
+    role: closed-loop-verifier
+    model: sonnet
+    permissions: supervised
+    phase: 3
+    prompt {
+      Verify a paired regression spec exists under e2e/walkthroughs/ for the
+      change and that its assertions use contract vocabulary (the same invariant
+      IDs). Default to fail if no spec pairs the change.
+    }
+    tools: [Read, Grep, Glob]
+    reads: ["workspace/build-report.md"]
+    writes: ["workspace/verify-closed-loop.md"]
+    outputs: {
+      verdict: pass | fail
+    }
+  }
+
+  # --- Human promote boundary (the deliberate workflow-split point) ---
+
+  human promote {
+    description: "Human reviews the contract delta + verify verdicts in the ship-report, then promotes to staging (which triggers the SEPARATE downstream regression workflow). Not in the autonomous loop until here."
+  }
+
+  # --- Flow (the execution DAG) ---
+
+  flow {
+    intake -> [contract-scout, blast-radius-mapper, boundary-drafter]
+    contract-scout -> builder
+    blast-radius-mapper -> builder
+    boundary-drafter -> builder
+    builder -> [security-verifier, contract-verifier, closed-loop-verifier]
+    security-verifier -> ship-report
+    contract-verifier -> ship-report
+    closed-loop-verifier -> ship-report
+    ship-report -> promote
+  }
+
+  # --- Gates (auto-injected; halt the autonomous run on verify failure) ---
+
+  gates {
+    gate verify-gate {
+      after: closed-loop-verifier
+      before: ship-report
+      run: "scripts/verify-gate.sh"
+      checks: [security, contract-conformance, closed-loop]
+      retry: 2
+      on-fail: bounce-back
+      behavior: blocking
+    }
+  }
+
+  # --- Blackboard (the substrate coupling host + embedded workflow) ---
+
+  memory {
+    workspace {
+      path: "workspace/"
+      structure: [ticket, contracts-touched, blast-radius, contract-delta, build-report, verify-security, verify-contract, verify-closed-loop]
+    }
+  }
+
+  # --- Hooks (host-layer concurrent observability — watch the Blackboard live) ---
+
+  hooks {
+    PostToolUse {
+      matcher: "Write"
+      type: command
+      command: "scripts/observe-blackboard.sh"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentopology",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "The declarative language for multi-agent systems. Write once, scaffold for any platform.",
   "author": "Nadav Naveh",
   "license": "Apache-2.0",