@jetrabbits/agentic 0.4.0 → 0.5.0

package/areas/devops/infrastructure/workflows/provision-environment.md

@@ -92,5 +92,34 @@ quality-gates:
 - Write `provision_report.md`: environment, resources created, cost estimate, next steps
 - **Done when:** report committed; outputs stored
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /provision-environment"])
+  role_1["devops-engineer"]
+  role_2["team-lead"]
+  step_1["1. Plan & Review"]
+  step_2["2. Apply Infrastructure"]
+  step_3["3. Configure Nodes (Ansible)"]
+  step_4["4. Smoke Tests"]
+  step_5["5. Document & Store Outputs"]
+  exit(["Terraform apply clean + Ansible 0 failures + smoke tests pass = environment..."])
+  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_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Terraform apply clean + Ansible 0 failures + smoke tests pass = environment provisioned.

package/areas/devops/kubernetes/workflows/cluster-bootstrap.md

@@ -190,5 +190,41 @@ quality-gates:
   - Set up `kube-prometheus-stack` for cluster monitoring
 - **Output:** `bootstrap_report.md` — cluster version, node IPs, installed components, kubeconfig location
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /cluster-bootstrap"])
+  role_1["devops-engineer"]
+  step_1["1. Node Pre-Flight"]
+  step_2["2. Bootstrap First Control Plane"]
+  step_3["3. Install CNI (Cilium)"]
+  step_4["4. Join Remaining Control Plane Nodes"]
+  step_5["5. Join Worker Nodes"]
+  step_6["6. etcd Encryption at Rest"]
+  step_7["7. Core Platform Components"]
+  step_8["8. Apply Security Baselines"]
+  exit(["All nodes Ready + core components Running + etcd encrypted + monitoring liv..."])
+  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 --> step_8
+  step_8 --> 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
+  role_1 -. owns .-> step_8
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 All nodes Ready + core components Running + etcd encrypted + monitoring live = cluster bootstrapped.

package/areas/devops/kubernetes/workflows/debug-workload.md

@@ -104,5 +104,34 @@ quality-gates:
 - **Output:** `docs/incidents/<date>-<workload>-root-cause.md`
 - **Done when:** document committed; alert/runbook created if pattern is recurring
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /debug-workload"])
+  role_1["devops-engineer"]
+  role_2["developer"]
+  step_1["1. Classify Symptom"]
+  step_2["2. Deep Diagnosis"]
+  step_3["3. Apply Fix"]
+  step_4["4. Verify & Monitor"]
+  step_5["5. Document"]
+  exit(["Pod Running + metrics stable + root cause documented = workload debug compl..."])
+  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_1 -. owns .-> step_2
+  role_2 -. owns .-> step_3
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Pod Running + metrics stable + root cause documented = workload debug complete.

package/areas/devops/kubernetes/workflows/onboard-service.md

@@ -120,5 +120,40 @@ quality-gates:
 - **Output:** metrics visible in Grafana; alerts configured
 - **Done when:** Grafana dashboard shows service metrics
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /onboard-service"])
+  role_1["devops-engineer"]
+  role_2["developer"]
+  step_1["1. Namespace Setup"]
+  step_2["2. RBAC Setup"]
+  step_3["3. Network Policies"]
+  step_4["4. Helm Chart"]
+  step_5["5. ArgoCD Application"]
+  step_6["6. Validate & Smoke Test"]
+  step_7["7. Monitoring"]
+  exit(["Pod Running + health check passing + ArgoCD Healthy + metrics visible = ser..."])
+  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_2 -. owns .-> step_4
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+  role_2 -. owns .-> step_6
+  role_1 -. owns .-> step_7
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Pod Running + health check passing + ArgoCD Healthy + metrics visible = service onboarded.

package/areas/devops/kubernetes/workflows/upgrade-cluster.md

@@ -146,6 +146,36 @@ kubectl get pdb -A
 - **Output:** `upgrade_report.md` — versions before/after, issues found, time taken
 - **Done when:** all Tier 1 services healthy; no unexpected pod restarts
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /upgrade-cluster"])
+  role_1["devops-engineer"]
+  role_2["team-lead"]
+  step_1["1. etcd Backup"]
+  step_2["2. Upgrade Control Plane (kubeadm)"]
+  step_3["3. Validate Control Plane"]
+  step_4["4. Upgrade Worker Nodes (rolling)"]
+  step_5["5. Post-Upgrade Validation"]
+  exit(["All nodes on target version + Tier 1 services healthy + upgrade report comm..."])
+  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_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+  role_2 -. owns .-> step_5
+  step_5 -. iterate if blocked .-> step_1
+```
+<!-- agent-diagram:end -->
+
 ## Rollback Plan
 
 ```bash

package/areas/devops/networking/workflows/onboard-ingress.md

@@ -60,5 +60,32 @@ done | sort | uniq -c
 - Point hostname to MetalLB external IP: `kubectl get svc -n ingress-nginx`
 - Add A record in DNS provider or internal CoreDNS
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /onboard-ingress"])
+  role_1["devops-engineer"]
+  step_1["1. Write Ingress Manifest"]
+  step_2["2. Apply & Wait for Certificate"]
+  step_3["3. Verify HTTPS"]
+  step_4["4. Verify Rate Limiting"]
+  step_5["5. DNS (if needed)"]
+  exit(["HTTPS accessible + cert issued + security headers present + rate limit veri..."])
+  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_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 HTTPS accessible + cert issued + security headers present + rate limit verified = ingress onboarded.

package/areas/devops/networking/workflows/service-mesh-onboard.md

@@ -118,5 +118,32 @@ kubectl -n istio-system port-forward svc/kiali 20001:20001 &
 ```
 - **Done when:** service visible in mesh dashboard; no unmeshed traffic warnings
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /service-mesh-onboard"])
+  role_1["devops-engineer"]
+  step_1["1. Pre-Check Mesh Health"]
+  step_2["2. Enable Injection"]
+  step_3["3. Verify mTLS"]
+  step_4["4. Apply Traffic Policies"]
+  step_5["5. Validate in Mesh Dashboard"]
+  exit(["Sidecar injected + mTLS verified + policies applied + dashboard shows servi..."])
+  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_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Sidecar injected + mTLS verified + policies applied + dashboard shows service = onboarded.

package/areas/devops/observability/workflows/alert-investigation.md

@@ -94,5 +94,34 @@ Saturation?
 - Is the alert threshold correct? (too sensitive = toil; too loose = misses real issues)
 - Create ticket if: runbook needs update, threshold needs tuning, or root cause needs a code fix
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /alert-investigation"])
+  role_1["devops-engineer"]
+  role_2["developer"]
+  step_1["1. Acknowledge & Classify"]
+  step_2["2. Correlate Signals"]
+  step_3["3. Identify Root Cause"]
+  step_4["4. Mitigate"]
+  step_5["5. Post-Investigation Notes"]
+  exit(["Alert resolved or escalated + root cause noted + runbook quality assessed =..."])
+  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_1 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_2 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_1 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Alert resolved or escalated + root cause noted + runbook quality assessed = investigation complete.

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.