From b29bb43a1459c36362e96b3174936b818997c12c Mon Sep 17 00:00:00 2001
From: Atharva-1512 <atharvagade403@gmail.com>
Date: Sat, 14 Mar 2026 00:14:57 +0530
Subject: [PATCH 1/2] Replace ASCII decision flow with Mermaid diagram

---
 docs/ARCHITECTURE.md | 44 +++++++++++++++++++++++++++-----------------
 1 file changed, 27 insertions(+), 17 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index f9f60ca..085254c 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -49,23 +49,33 @@ Agents can respond with just `PASS` if they genuinely have nothing meaningful to
 Beyond the configured turn interval, the `needs_human_input()` method performs an additional check: if the **last agent message explicitly addresses the user by name**, the HITL prompt fires immediately. This ensures the conversation never inadvertently "speaks for" the human participant.
 
 **Decision Flow:**
-```
-generate_next_turn()
-    ↓
-Orchestrator due? → speak (or PASS → skip)
-    ↓
-_forced_next_agent set? → use it, clear it
-    ↓
-session_type = DYNAMIC?
-    → @mention in last message? → forced agent
-    → Score all agents by expertise → pick best
-    → fallback: round robin
-    ↓
-agent.generate_response()
-    ↓
-response == "PASS"? → skip, return {skipped: True}
-    ↓
-append to history with timestamp, return turn_data
+```mermaid
+flowchart TD
+
+A[generate_next_turn()] --> B{Orchestrator due?}
+B -->|Yes| C[Speak or PASS → skip]
+B -->|No| D{_forced_next_agent set?}
+
+D -->|Yes| E[Use forced agent and clear flag]
+D -->|No| F{session_type = DYNAMIC?}
+
+F -->|Yes| G{@mention in last message?}
+G -->|Yes| H[Use mentioned agent]
+G -->|No| I[Score agents by expertise]
+
+I --> J[Pick best agent]
+J --> K[Fallback: round robin]
+
+F -->|No| K
+
+K --> L[agent.generate_response()]
+
+L --> M{response == PASS?}
+
+M -->|Yes| N[Skip turn return skipped true]
+M -->|No| O[Append to history with timestamp]
+
+O --> P[Return turn_data]
 ```
 
 ## Custom Model Integrations (Bring Your Own Code)

From 3ad7d62bfdec0f99932cd3ac2c573674130579bd Mon Sep 17 00:00:00 2001
From: Atharva-1512 <atharvagade403@gmail.com>
Date: Fri, 20 Mar 2026 19:46:55 +0530
Subject: [PATCH 2/2] Refactor flowchart in ARCHITECTURE.md

fix issue #12
---
 docs/ARCHITECTURE.md | 29 ++++++++++++++---------------
 1 file changed, 14 insertions(+), 15 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 085254c..51c14e5 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -53,29 +53,28 @@ Beyond the configured turn interval, the `needs_human_input()` method performs a
 flowchart TD
 
 A[generate_next_turn()] --> B{Orchestrator due?}
-B -->|Yes| C[Speak or PASS → skip]
-B -->|No| D{_forced_next_agent set?}
+B -->|Yes| C[Speak or PASS]
+C -->|Speak| EndOrch[Append to history & return turn]
+C -->|PASS| D
 
-D -->|Yes| E[Use forced agent and clear flag]
+B -->|No| D{_forced_next_agent set?}
+D -->|Yes| E[Use forced agent & clear flag] --> L
 D -->|No| F{session_type = DYNAMIC?}
 
+F -->|No| K[Fallback: round robin / argumentative] --> L
 F -->|Yes| G{@mention in last message?}
-G -->|Yes| H[Use mentioned agent]
-G -->|No| I[Score agents by expertise]
 
-I --> J[Pick best agent]
-J --> K[Fallback: round robin]
-
-F -->|No| K
-
-K --> L[agent.generate_response()]
+G -->|Yes| H[Use mentioned agent] --> L
+G -->|No| I[Score agents by expertise]
 
-L --> M{response == PASS?}
+I --> J{Top score > 0?}
+J -->|Yes| Best[Pick best matching agent] --> L
+J -->|No| K
 
-M -->|Yes| N[Skip turn return skipped true]
-M -->|No| O[Append to history with timestamp]
+L[agent.generate_response()] --> M{response == PASS?}
 
-O --> P[Return turn_data]
+M -->|Yes| N[Skip turn, return skipped: True]
+M -->|No| O[Append to history with timestamp] --> P[Return turn_data]
 ```
 
 ## Custom Model Integrations (Bring Your Own Code)