@jetrabbits/agentic 0.3.3 → 0.5.0

package/areas/devops/observability/workflows/observability-stack-setup.md

@@ -152,5 +152,38 @@ for dashboard in infra/observability/dashboards/*.json; do
 done
 ```
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /observability-stack-setup"])
+  role_1["devops-engineer"]
+  step_1["1. Namespace & Prerequisites"]
+  step_2["2. kube-prometheus-stack (Prometheus + Grafana + Alertmanager)"]
+  step_3["3. Loki + Promtail (Logs)"]
+  step_4["4. Tempo (Traces)"]
+  step_5["5. OpenTelemetry Collector (DaemonSet)"]
+  step_6["6. Validate Stack"]
+  step_7["7. Import Dashboards"]
+  exit(["All 4 components healthy + test alert fired + dashboards showing data = sta..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> step_6
+  step_6 --> step_7
+  step_7 --> exit
+  role_1 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+  role_1 -. owns .-> step_6
+  role_1 -. owns .-> step_7
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 All 4 components healthy + test alert fired + dashboards showing data = stack deployed.

package/areas/devops/observability/workflows/onboard-service-monitoring.md

@@ -79,5 +79,36 @@ spec:
 - Link trace panel (Tempo datasource) to request duration panel
 - **Done when:** dashboard saved in `infra/dashboards/`; Grafana shows live data
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /onboard-service-monitoring"])
+  role_1["developer"]
+  role_2["devops-engineer"]
+  step_1["1. Metrics Instrumentation"]
+  step_2["2. ServiceMonitor"]
+  step_3["3. Tracing Instrumentation"]
+  step_4["4. Log Labels"]
+  step_5["5. Alert Rules"]
+  step_6["6. Grafana Dashboard"]
+  exit(["Golden signals in Prometheus + logs in Loki + traces in Tempo + alerts depl..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> step_6
+  step_6 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_2 -. owns .-> step_4
+  role_2 -. owns .-> step_5
+  role_2 -. owns .-> step_6
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Golden signals in Prometheus + logs in Loki + traces in Tempo + alerts deployed + dashboard live = service monitored.

package/areas/devops/sre/workflows/incident-response.md

@@ -62,5 +62,53 @@ quality-gates:
 - Define action items with owners and due dates
 - Publish to team wiki; announce in #postmortems
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /incident-response"])
+  role_1["devops-engineer"]
+  role_2["developer"]
+  role_3["pm"]
+  role_4["devops-engineer (IC)"]
+  role_5["developer (technical lead)"]
+  role_6["pm (comms)"]
+  step_1["T+0–5: Acknowledge & Scope"]
+  step_2["T+5–15: Mitigate"]
+  step_3["T+10: Communicate"]
+  step_4["T+15–30: Stabilize"]
+  step_5["T+30: Resolve or Escalate"]
+  step_6["T+60: Preliminary Postmortem"]
+  step_7["T+24h: Full Postmortem"]
+  exit(["Service healthy + stakeholders informed + postmortem published = incident c..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> step_6
+  step_6 --> step_7
+  step_7 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_2
+  role_1 -. owns .-> step_2
+  role_3 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_2 -. owns .-> step_5
+  role_4 -. owns .-> step_5
+  role_5 -. owns .-> step_5
+  role_6 -. owns .-> step_5
+  role_2 -. owns .-> step_6
+  role_4 -. owns .-> step_6
+  role_5 -. owns .-> step_6
+  role_6 -. owns .-> step_6
+  role_2 -. owns .-> step_7
+  role_4 -. owns .-> step_7
+  role_5 -. owns .-> step_7
+  role_6 -. owns .-> step_7
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Service healthy + stakeholders informed + postmortem published = incident closed.

package/areas/devops/sre/workflows/postmortem.md

@@ -86,5 +86,37 @@ done
 - Any blocked items? Need resource allocation?
 - If root cause not addressed: escalate to engineering lead
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /postmortem"])
+  role_1["devops-engineer"]
+  role_2["team-lead"]
+  step_1["1. Collect Data (within 2h of resolution)"]
+  step_2["2. Draft Postmortem"]
+  step_3["3. 5-Whys Facilitation Meeting (within 48h)"]
+  step_4["4. Finalize Document"]
+  step_5["5. Publish & Track"]
+  step_6["6. Follow-Up (2 weeks later)"]
+  exit(["Postmortem published + all action items in tracker + team notified = postmo..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> step_6
+  step_6 --> exit
+  role_1 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+  role_2 -. owns .-> step_5
+  role_2 -. owns .-> step_6
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Postmortem published + all action items in tracker + team notified = postmortem complete.

package/areas/devops/sre/workflows/slo-review.md

@@ -21,7 +21,6 @@ related-rules:
   - error-budget-policy.md
 uses-skills:
   - slo-sli-design
-  - slo-implementation
   - capacity-planning
 quality-gates:
   - SLO targets grounded in actual reliability data (not aspirational)
@@ -91,5 +90,40 @@ kubectl apply -f rules/slo-${SERVICE}-generated.yaml -n monitoring
 - notify: tighten SLO to 99.3%; generates meaningful error budget
 ```
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /slo-review"])
+  role_1["devops-engineer"]
+  role_2["team-lead"]
+  role_3["product-owner"]
+  step_1["1. Pull Reliability Data"]
+  step_2["2. Classify Services"]
+  step_3["3. SLO Adjustment Workshop"]
+  step_4["4. Update SLO Definitions"]
+  step_5["5. Error Budget Policy Review"]
+  step_6["6. Publish SLO Review Report"]
+  exit(["Report published + SLO changes applied + action items in tracker = review c..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> step_6
+  step_6 --> exit
+  role_1 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_2 -. owns .-> step_3
+  role_3 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_2 -. owns .-> step_5
+  role_3 -. owns .-> step_5
+  role_1 -. owns .-> step_6
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Report published + SLO changes applied + action items in tracker = review complete.

package/areas/software/backend/workflows/add-migration.md

@@ -72,6 +72,39 @@ quality-gates:
 - **Output:** `migration_readiness.md` with deployment steps, rollback command, monitoring checklist
 - **Done when:** ops/release team has everything needed to deploy safely
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /add-migration"])
+  role_1["team-lead"]
+  role_2["developer"]
+  role_3["qa"]
+  role_4["pm"]
+  step_1["1. Risk & Compatibility Analysis"]
+  step_2["2. Migration Implementation"]
+  step_3["3. Test DB Validation & Data Checks"]
+  step_4["4. Review & Remediation Loop"]
+  step_5["5. Readiness Report"]
+  exit(["Validated migration + readiness report + @team-lead approval = ready to dep..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_2
+  role_3 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_2 -. owns .-> step_4
+  role_4 -. owns .-> step_5
+  role_1 -. owns .-> step_5
+  step_5 -. iterate if blocked .-> step_1
+```
+<!-- agent-diagram:end -->
+
 ## Iteration Loop
 If validation reveals data issues or compatibility risks → return to Step 1 for strategy revision.
 

package/areas/software/backend/workflows/create-endpoint.md

@@ -85,5 +85,45 @@ quality-gates:
 - **Output:** endpoint accepted; delivery note in `docs/<feature>/delivery_summary.md`
 - **Done when:** `@product-owner` signs off
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /create-endpoint"])
+  role_1["product-owner"]
+  role_2["pm"]
+  role_3["team-lead"]
+  role_4["developer"]
+  role_5["qa"]
+  step_1["1. Scope & Contract"]
+  step_2["2. Architecture Review"]
+  step_3["3. Implementation"]
+  step_4["4. Test Design & Execution"]
+  step_5["5. Code Review & Sign-off"]
+  step_6["6. Fix / Retest Loop"]
+  step_7["7. Acceptance"]
+  exit(["Accepted endpoint + passing tests + @team-lead sign-off = ready to merge."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> step_6
+  step_6 --> step_7
+  step_7 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_1
+  role_3 -. owns .-> step_2
+  role_4 -. owns .-> step_3
+  role_5 -. owns .-> step_4
+  role_3 -. owns .-> step_5
+  role_4 -. owns .-> step_6
+  role_5 -. owns .-> step_6
+  role_1 -. owns .-> step_7
+  role_2 -. owns .-> step_7
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Accepted endpoint + passing tests + `@team-lead` sign-off = ready to merge.

package/areas/software/backend/workflows/debug-issue.md

@@ -73,5 +73,36 @@ quality-gates:
 - **Output:** `root_cause_summary.md` — what failed, why, how fixed, how to prevent
 - **Done when:** `@team-lead` approves fix; root cause documented; ticket closed
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /debug-issue"])
+  role_1["pm"]
+  role_2["team-lead"]
+  role_3["developer"]
+  role_4["qa"]
+  step_1["1. Triage & Impact Classification"]
+  step_2["2. Reproduce & Isolate"]
+  step_3["3. Fix Implementation"]
+  step_4["4. Verification & Regression Checks"]
+  step_5["5. Technical Review & Closure"]
+  exit(["Merged fix + verified resolution + root cause documented = incident closed."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_1
+  role_3 -. owns .-> step_2
+  role_3 -. owns .-> step_3
+  role_4 -. owns .-> step_4
+  role_2 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Merged fix + verified resolution + root cause documented = incident closed.

package/areas/software/backend/workflows/develop-epic.md

@@ -71,6 +71,43 @@ quality-gates:
 - **Output:** `docs/<epic>/delivery_summary.md` — accepted items, deferred items, follow-up backlog
 - **Done when:** epic accepted; follow-up items logged
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /develop-epic"])
+  role_1["product-owner"]
+  role_2["pm"]
+  role_3["team-lead"]
+  role_4["developer"]
+  role_5["qa"]
+  step_1["1. Epic Decomposition & Milestone Planning"]
+  step_2["2. Architecture Runway Definition"]
+  step_3["3. Increment Implementation"]
+  step_4["4. Increment Verification"]
+  step_5["5. Milestone Review & Replanning"]
+  step_6["6. Final Acceptance"]
+  exit(["All increments accepted by @product-owner + clean regression suite = epic d..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> step_6
+  step_6 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_1
+  role_3 -. owns .-> step_2
+  role_4 -. owns .-> step_3
+  role_5 -. owns .-> step_4
+  role_2 -. owns .-> step_5
+  role_3 -. owns .-> step_5
+  role_1 -. owns .-> step_6
+  step_6 -. iterate if blocked .-> step_1
+```
+<!-- agent-diagram:end -->
+
 ## Iteration Loop
 Steps 3–5 repeat for each increment. Replanning in Step 5 governs scope adjustments.
 

package/areas/software/backend/workflows/develop-feature.md

@@ -85,6 +85,50 @@ quality-gates:
 - **Output:** `docs/<feature>/delivery_summary.md` — accepted / deferred with rationale
 - **Done when:** feature accepted or explicitly deferred
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /develop-feature"])
+  role_1["product-owner"]
+  role_2["pm"]
+  role_3["team-lead"]
+  role_4["designer"]
+  role_5["developer"]
+  role_6["qa"]
+  step_1["1. Requirements & Value Framing"]
+  step_2["2. Solution Design & Risk Plan"]
+  step_3["3. Implementation"]
+  step_4["4. Risk-Based Verification"]
+  step_5["5. Code Review & Architecture Sign-off"]
+  step_6["6. Fix / Retest Loop"]
+  step_7["7. Acceptance & Final Report"]
+  exit(["@product-owner acceptance + no unresolved blockers = feature complete and r..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> step_6
+  step_6 --> step_7
+  step_7 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_1
+  role_3 -. owns .-> step_2
+  role_4 -. owns .-> step_2
+  role_5 -. owns .-> step_3
+  role_6 -. owns .-> step_4
+  role_3 -. owns .-> step_5
+  role_5 -. owns .-> step_6
+  role_6 -. owns .-> step_6
+  role_2 -. owns .-> step_6
+  role_1 -. owns .-> step_7
+  role_2 -. owns .-> step_7
+  step_7 -. iterate if blocked .-> step_1
+```
+<!-- agent-diagram:end -->
+
 ## Iteration Loop
 Steps 3–6 repeat per increment for large features. `@pm` tracks scope changes and timeline impact.
 

package/areas/software/backend/workflows/refactor-module.md

@@ -69,5 +69,40 @@ quality-gates:
 - **Output:** merge approval + note in `refactor_plan.md`: "Goal achieved: <description>"
 - **Done when:** PR merged
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /refactor-module"])
+  role_1["team-lead"]
+  role_2["qa"]
+  role_3["developer"]
+  step_1["1. Refactor Plan & Boundaries"]
+  step_2["2. Baseline Test Coverage"]
+  step_3["3. Incremental Refactor Implementation"]
+  step_4["4. Regression Validation"]
+  step_5["5. Review / Fix Loop"]
+  step_6["6. Closure with Parity Report"]
+  exit(["Merged refactor + behavior parity confirmed + improvement goal achieved = r..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> step_6
+  step_6 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_2
+  role_3 -. owns .-> step_2
+  role_3 -. owns .-> step_3
+  role_2 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+  role_3 -. owns .-> step_5
+  role_2 -. owns .-> step_5
+  role_1 -. owns .-> step_6
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Merged refactor + behavior parity confirmed + improvement goal achieved = refactor complete.

package/areas/software/backend/workflows/test-feature.md

@@ -63,5 +63,35 @@ quality-gates:
 - **Output:** `quality_report.md`; stable CI run evidence
 - **Done when:** zero flaky tests; coverage meets threshold; report complete
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /test-feature"])
+  role_1["qa"]
+  role_2["developer"]
+  role_3["team-lead"]
+  step_1["1. Coverage Gap Analysis"]
+  step_2["2. Testability Adjustments"]
+  step_3["3. Automated Test Implementation"]
+  step_4["4. Review of Scenarios & Assertions"]
+  step_5["5. Stability Run & Reporting"]
+  exit(["Stable test suite + coverage threshold met + @team-lead approval = tests re..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_2 -. owns .-> step_3
+  role_3 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Stable test suite + coverage threshold met + `@team-lead` approval = tests ready to merge.

package/areas/software/data-engineering/workflows/backfill-data.md

@@ -55,5 +55,30 @@ quality-gates:
 - **Output:** `validation_report.md` — row counts, metric comparison, dbt test results
 - **Done when:** all tests pass; metrics match expected; consumers notified
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /backfill-data"])
+  role_1["developer"]
+  role_2["qa"]
+  step_1["1. Impact Assessment"]
+  step_2["2. Dry Run"]
+  step_3["3. Execute Backfill"]
+  step_4["4. Post-Backfill Validation"]
+  exit(["Validated backfill + notified consumers + @team-lead sign-off = backfill co..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_2 -. owns .-> step_4
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Validated backfill + notified consumers + `@team-lead` sign-off = backfill complete.

package/areas/software/data-engineering/workflows/data-quality-incident.md

@@ -60,5 +60,36 @@ quality-gates:
 - **Output:** postmortem; monitoring updated; dbt tests updated
 - **Done when:** postmortem reviewed; prevention measures in place
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /data-quality-incident"])
+  role_1["qa"]
+  role_2["developer"]
+  role_3["team-lead"]
+  step_1["1. Scope & Triage"]
+  step_2["2. Quarantine"]
+  step_3["3. Root Cause Isolation"]
+  step_4["4. Remediation"]
+  step_5["5. Post-Incident"]
+  exit(["Clean model + postmortem published + prevention measures added = incident c..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_2 -. owns .-> step_3
+  role_2 -. owns .-> step_4
+  role_3 -. owns .-> step_5
+  role_1 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Clean model + postmortem published + prevention measures added = incident closed.

package/areas/software/data-engineering/workflows/lineage-trace.md

@@ -52,5 +52,30 @@ quality-gates:
 - **Output:** `lineage_report.md` with diagram, summary, and checklist
 - **Done when:** report reviewed and ready to share with affected owners
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /lineage-trace"])
+  role_1["developer"]
+  role_2["team-lead"]
+  step_1["1. Parse Target"]
+  step_2["2. Trace Lineage"]
+  step_3["3. Impact Assessment"]
+  step_4["4. Generate Report"]
+  exit(["Published lineage report + migration checklist = ready to plan the change s..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> exit
+  role_1 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_2 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Published lineage report + migration checklist = ready to plan the change safely.

package/areas/software/data-engineering/workflows/new-model.md

@@ -67,5 +67,35 @@ quality-gates:
 - **Actions:** review SQL logic, naming conventions, documentation completeness; approve or return with blocking feedback
 - **Done when:** `@team-lead` approves; PR merged
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /new-model"])
+  role_1["pm"]
+  role_2["team-lead"]
+  role_3["developer"]
+  role_4["qa"]
+  step_1["1. Requirements Gathering"]
+  step_2["2. Model Design"]
+  step_3["3. SQL & YAML Implementation"]
+  step_4["4. Validation"]
+  step_5["5. Review & Merge"]
+  exit(["Passing dbt tests + complete YAML docs + @team-lead approval = model produc..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_2
+  role_3 -. owns .-> step_3
+  role_4 -. owns .-> step_4
+  role_2 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Passing dbt tests + complete YAML docs + `@team-lead` approval = model production-ready.

package/areas/software/data-engineering/workflows/schema-migration.md

@@ -63,5 +63,34 @@ quality-gates:
 - **Output:** `validation_report.md`; catalog updated; owners notified
 - **Done when:** all tests green; documentation current
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /schema-migration"])
+  role_1["team-lead"]
+  role_2["developer"]
+  role_3["qa"]
+  step_1["1. Change Classification"]
+  step_2["2. Impact Assessment"]
+  step_3["3. Migration Strategy"]
+  step_4["4. Execute Migration"]
+  step_5["5. Verify & Document"]
+  exit(["Post-migration tests green + catalog updated + owners notified = migration..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_2 -. owns .-> step_4
+  role_3 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Post-migration tests green + catalog updated + owners notified = migration complete.