Agenttien viestintäkartta — blue-marlin

Kieli: English → agents-communications-map.en.md

Tämä asiakirja generoidaan automaattisesti projektin oppimismerkinnästä (learnings/blue-marlin.yaml), agenttimäärittelyistä kansiossa agents/ ja tiedostosta agents/MANIFEST.yaml.

• Projekti: blue-marlin — Standalone Python tooling for parametric CAD model generation with bill-of-materials extraction (FreeCAD + CadQuery).
• Framework: agents-govern v0.34.0
• Aktiivisia agentteja: 6 yhteensä 12 saatavilla

Huom. Tämän kartan "agentit" eivät ole itsenäisiä palveluita. Ne ovat roolimäärittelyjä (YAML-tiedostoja kansiossa agents/), joita yksi LLM-ajuri (yleensä Claude) suorittaa. Kartta näyttää, mikä rooli toimii missäkin vaiheessa ja mikä artefakti siirtyy seuraavalle roolille. Ihmis-hallinnoijalla on lopullinen hyväksymisvalta portilla 2.

Yleisnäkymä

flowchart TB
    H["Ihmis-hallinnoija"]:::human
    Claude["Claude AI
(LLM-ajuri)"]:::ai

    subgraph PROD["Tuotantoagentit"]
        coder_tester["coder-tester
v0.3.2"]:::prod
        planner_architect["planner-architect
v0.4.0"]:::prod
    end
    subgraph GOV["Hallinto"]
        governor_reviewer["governor-reviewer
v0.4.0"]:::gov
    end
    subgraph CROSS["Poikkileikkaavat"]
        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 -->|"tarkoitus / pyyntö"| planner_architect
    planner_architect -->|"suunnitelma + design"| coder_tester
    planner_architect -->|"doc-määrittely"| documentation_writer
    coder_tester -->|"koodi + testit"| governor_reviewer
    documentation_writer -->|"doc-luonnos"| governor_reviewer
    governor_reviewer -->|"oppimismerkinnät"| infosec_sentinel
    governor_reviewer -->|"kontribuutiot"| contribution_auditor
    governor_reviewer -->|"hyväksy / estä"| H
    H -->|"git push"| GIT["git + GitLab CI"]:::tool
    H -->|"lähetä"| UP["Yläjuoksu agents-govern"]:::ext

    Claude -.->|"näyttelee"| coder_tester
    Claude -.->|"näyttelee"| contribution_auditor
    Claude -.->|"näyttelee"| documentation_writer
    Claude -.->|"näyttelee"| 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

Tyypillisen iteraation kulku

sequenceDiagram
    autonumber
    actor H as Ihmis-hallinnoija
    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 pyyntö (esim. "vaihda paalumateriaalia")
    PA->>PA: Vaihe 1 — selkiytä tarkoitus, vaihtoehdot, rajoitteet
    PA->>CT: Suunnitelma + hyväksymisehdot
    CT->>CT: TDD — RED → GREEN → REFACTOR
    CT->>DW: Perustelu + uudet artefaktit
    DW->>GR: Päivitetyt käyttäjädokumentit
    CT->>GR: Koodi-diff + testi-diff
    GR->>IS: Uudet oppimismerkinnät
    IS-->>GR: Hyväksy / hylkää / varoita
    GR-->>H: Portti 2 -review-paketti
    H->>Git: Hyväksy → commit → push
    Git->>Git: CI: pytest-invariantit + Pages-deploy

Aktiiviset agentit

Inaktiiviset (keskeytetty / ohitettu / saatavilla mutta ei käytössä)

Viestintäkanavat — mitä siirtyy mihin

Laatuportit (Gates)

Frameworkissa määritellyt laatuportit (gates). Portti on aktiivinen tässä projektissa, jos sen vastuuagentti on aktiivisten joukossa; muuten ei aktivoitu. Neuvoa-antavat agentit eivät blokkaa porttia, mutta niiden löydökset näkyvät katselmointipaketissa.

Portti 1 — suunnitelman hyväksyntä

• Vastuuagentti: governor-reviewer
• Neuvoa-antavat: fact-checker — ei aktiivisten joukossa, ei tuota raporttia
• Milloin: ennen jokaista toteutusiteraatiota (paitsi fast-track)
• Tila tässä projektissa: 🟢 aktiivinen

Governor-Reviewer hyväksyy suunnitelman ennen toteutuksen aloittamista. Fact-Checker tarkistaa suunnitelmassa olevat viittaukset olemassa olevaan koodiin (jos sellaisia on). Voidaan ohittaa fast-track-menettelyllä pieniin matalan riskin tehtäviin (ks. simplicity-rule).

Portti 2 — toteutuksen hyväksyntä

• Vastuuagentti: governor-reviewer
• Neuvoa-antavat: infosec-sentinel, contribution-auditor
• Milloin: ennen jokaista commitia / mergeä
• Tila tässä projektissa: 🟢 aktiivinen

Governor-Reviewer soveltaa poikkileikkaavat tarkistuslistat (security, accessibility, audit, regression-guard). Poikkileikkaavat agentit (infosec-sentinel, contribution-auditor) antavat neuvoa-antavia raportteja. Lopullinen hyväksyntä ennen mergeä. Tätä porttia ei voi koskaan ohittaa — fast-track ohittaa vain Portin 1.

Generoitu 2026-04-26 21:36 UTC skriptillä tools/render_agents_map.py (paikallinen prototyyppi; yläjuoksuehdokas agov-render-agents-map — ks. upstream-submissions/E1-agov-render-agents-map.md).