Agents communications map — blue-marlin

Language: Suomeksi → agents-communications-map.md

This document is auto-generated from the project's learning record (learnings/blue-marlin.yaml), the agent definitions in agents/ and agents/MANIFEST.yaml.

• Project: blue-marlin — Standalone Python tooling for parametric CAD model generation with bill-of-materials extraction (FreeCAD + CadQuery).
• Framework: agents-govern v0.34.0
• Active agents: 6 of 12 available

Note. The "agents" here are not autonomous services. They are role definitions (YAML files in agents/) executed by a single LLM driver (typically Claude). The map shows which role is acting at which point and which artifact is handed to which next role. The Human Governor holds final approval authority at Gate 2.

High-level diagram

flowchart TB
    H["Human Governor"]:::human
    Claude["Claude AI
(LLM driver)"]:::ai

    subgraph PROD["Production agents"]
        coder_tester["coder-tester
v0.3.2"]:::prod
        planner_architect["planner-architect
v0.4.0"]:::prod
    end
    subgraph GOV["Governance"]
        governor_reviewer["governor-reviewer
v0.4.0"]:::gov
    end
    subgraph CROSS["Cross-cutting"]
        contribution_auditor["contribution-auditor
v0.1.0"]:::cross
        documentation_writer["documentation-writer
v0.1.0"]:::cross
        infosec_sentinel["infosec-sentinel
v0.1.0"]:::cross
    end

    H -->|"intent / request"| planner_architect
    planner_architect -->|"plan + design"| coder_tester
    planner_architect -->|"doc spec"| documentation_writer
    coder_tester -->|"code + tests"| governor_reviewer
    documentation_writer -->|"draft docs"| governor_reviewer
    governor_reviewer -->|"learning records"| infosec_sentinel
    governor_reviewer -->|"contributions"| contribution_auditor
    governor_reviewer -->|"approve / block"| H
    H -->|"git push"| GIT["git + GitLab CI"]:::tool
    H -->|"submit"| UP["Upstream agents-govern"]:::ext

    Claude -.->|"plays"| coder_tester
    Claude -.->|"plays"| contribution_auditor
    Claude -.->|"plays"| documentation_writer
    Claude -.->|"plays"| planner_architect

    classDef human fill:#fce5b6,stroke:#c08020,stroke-width:2px,color:#333
    classDef ai fill:#e6dcfa,stroke:#8060c0,stroke-width:2px,color:#333
    classDef prod fill:#d4edda,stroke:#28a745,stroke-width:1px,color:#333
    classDef gov fill:#cce5ff,stroke:#0066cc,stroke-width:2px,color:#333
    classDef cross fill:#f8d7da,stroke:#dc3545,stroke-width:1px,color:#333
    classDef other fill:#eeeeee,stroke:#888,stroke-width:1px,color:#333
    classDef tool fill:#e2e3e5,stroke:#6c757d,stroke-width:1px,color:#333
    classDef ext fill:#fff3cd,stroke:#cc9900,stroke-width:1px,color:#333

Single-iteration sequence (typical)

sequenceDiagram
    autonumber
    actor H as Human Governor
    participant PA as planner-architect
    participant CT as coder-tester
    participant DW as documentation-writer
    participant GR as governor-reviewer
    participant IS as infosec-sentinel
    participant CA as contribution-auditor
    participant Git as git + GitLab CI

    H->>PA: Iter N request (e.g., "switch pile material")
    PA->>PA: Phase 1 — clarify intent, alternatives, constraints
    PA->>CT: Plan + acceptance criteria
    CT->>CT: TDD — RED → GREEN → REFACTOR
    CT->>DW: Rationale + new artifacts
    DW->>GR: Updated user-facing docs
    CT->>GR: Code diff + test diff
    GR->>IS: New learning-record entries
    IS-->>GR: Pass / fail / warn
    GR-->>H: Gate 2 review packet
    H->>Git: Approve → commit → push
    Git->>Git: CI: pytest invariants + Pages deploy

Active agents

Inactive (suspended / skipped / available-but-unused)

Communication channels — what flows where

Quality gates

Quality gates as defined in the framework. A gate is active in this project if its owner agent is in the active set; otherwise not activated. Advisory agents do not block the gate, but their findings appear in the review packet.

Gate 1 — plan approval

• Owner agent: governor-reviewer
• Advisory: fact-checker — not in active set, produces no report
• When: before each implementation iteration (unless fast-tracked)
• Status in this project: 🟢 active

Governor-Reviewer approves the plan before implementation begins. Fact-Checker verifies factual claims in the plan against the actual codebase (if the plan references existing code). Can be waived via fast-track for small, low-risk tasks (see simplicity-rule).

Gate 2 — implementation approval

• Owner agent: governor-reviewer
• Advisory: infosec-sentinel, contribution-auditor
• When: before every commit / merge
• Status in this project: 🟢 active

Governor-Reviewer applies cross-cutting checklists (security, accessibility, audit, regression-guard). Cross-cutting agents (infosec-sentinel, contribution-auditor) provide advisory reports. Final approval before merge. This gate is never waived — fast-track only waives Gate 1.

Generated 2026-04-26 21:36 UTC by tools/render_agents_map.py (local prototype; upstream candidate agov-render-agents-map — see upstream-submissions/E1-agov-render-agents-map.md).