BasicFist · Camier · Nov 14, 2025
diff --git a/MODE-FRAMEWORK-MIGRATION.md b/MODE-FRAMEWORK-MIGRATION.md
@@ -11,12 +11,12 @@ The mode framework (`lib/mode-framework.sh`) centralizes common initialization l
 
 ### Already Migrated
 - ✅ **pair-programming.sh** - Reduced from 83 lines → 60 lines
+- ✅ **debate.sh** - Uses framework + `protocols/debate-protocol.txt`
+- ✅ **teaching.sh** - Uses framework + `protocols/teaching-protocol.txt`
+- ✅ **consensus.sh** - Uses framework + `protocols/consensus-protocol.txt`
+- ✅ **competition.sh** - Uses framework + `protocols/competition-protocol.txt`
 
-### To Migrate
-- ⏳ **debate.sh**
-- ⏳ **teaching.sh**
-- ⏳ **consensus.sh**
-- ⏳ **competition.sh**
+All legacy collaboration modes are now on the shared framework. The "To Migrate" section is intentionally left empty for future modes.
 
 ---
 

diff --git a/kitty/scripts/ai-agent-broadcast.sh b/kitty/scripts/ai-agent-broadcast.sh
@@ -6,7 +6,11 @@
 
 set -euo pipefail
 
-SESSION=${KITTY_AI_SESSION:-ai-agents}
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/lib/constants.sh"
+source "${SCRIPT_DIR}/lib/shared-state.sh"
+
+SESSION="$AI_AGENTS_SESSION"
 MESSAGE="${1:-}"
 
 if [[ -z "$MESSAGE" ]]; then
@@ -28,4 +32,4 @@ tmux send-keys -t "$SESSION":0.1 "# BROADCAST: $MESSAGE" C-m
 
 # Also send to shared file
 TIMESTAMP=$(date '+%H:%M:%S')
-echo "[$TIMESTAMP] [BROADCAST] $MESSAGE" >> /tmp/ai-agents-shared.txt
+echo "[$TIMESTAMP] [BROADCAST] $MESSAGE" >> "$AI_AGENTS_SHARED_FILE"
diff --git a/kitty/scripts/ai-agent-progress.sh b/kitty/scripts/ai-agent-progress.sh
@@ -6,12 +6,11 @@
 
 set -euo pipefail
 
-SHARED_FILE="/tmp/ai-agents-shared.txt"
-
-# Source color library
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/lib/colors.sh"
 source "${SCRIPT_DIR}/lib/temp-files.sh"
+source "${SCRIPT_DIR}/lib/constants.sh"
+source "${SCRIPT_DIR}/lib/shared-state.sh"
 
 usage() {
     cat <<EOF
@@ -87,26 +86,26 @@ if [[ "$UPDATE_MODE" == true ]]; then
         TASK_PLAIN=$(echo "$TASK" | sed 's/\x1B\[[0-9;]*[JKmsu]//g')
 
         # Create temp file with updated line
-        if grep -q "$TASK_PLAIN" "$SHARED_FILE" 2>/dev/null; then
+        if grep -q "$TASK_PLAIN" "$AI_AGENTS_SHARED_FILE" 2>/dev/null; then
             # Update existing line (secure temp file with auto-cleanup)
             TMP_FILE=$(temp_file)
-            tac "$SHARED_FILE" | awk -v task="$TASK_PLAIN" -v msg="$MESSAGE" '
+            tac "$AI_AGENTS_SHARED_FILE" | awk -v task="$TASK_PLAIN" -v msg="$MESSAGE" '
                 !found && $0 ~ task { print msg; found=1; next }
                 { print }
             ' | tac > "$TMP_FILE"
-            cat "$TMP_FILE" > "$SHARED_FILE"
+            cat "$TMP_FILE" > "$AI_AGENTS_SHARED_FILE"
         else
             # No existing line, append
-            echo -e "$MESSAGE" >> "$SHARED_FILE"
+            echo -e "$MESSAGE" >> "$AI_AGENTS_SHARED_FILE"
         fi
     else
         # Fallback: just append
-        echo -e "$MESSAGE" >> "$SHARED_FILE"
+        echo -e "$MESSAGE" >> "$AI_AGENTS_SHARED_FILE"
     fi
 else
     # Normal mode: append
-    echo -e "$MESSAGE" >> "$SHARED_FILE"
+    echo -e "$MESSAGE" >> "$AI_AGENTS_SHARED_FILE"
 fi
 
 # Also log to structured log
-echo "[$TIMESTAMP] [$AGENT_ID] [PROGRESS] $TASK: $CURRENT/$TOTAL ($PERCENT%)" >> "${SHARED_FILE}.log"
+echo "[$TIMESTAMP] [$AGENT_ID] [PROGRESS] $TASK: $CURRENT/$TOTAL ($PERCENT%)" >> "${AI_AGENTS_SHARED_FILE}.log"
diff --git a/kitty/scripts/ai-agent-send-enhanced.sh b/kitty/scripts/ai-agent-send-enhanced.sh
@@ -6,12 +6,12 @@
 
 set -euo pipefail
 
-SHARED_FILE="/tmp/ai-agents-shared.txt"
-SESSION=${KITTY_AI_SESSION:-ai-agents}
-
-# Source color library
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/lib/colors.sh"
+source "${SCRIPT_DIR}/lib/constants.sh"
+source "${SCRIPT_DIR}/lib/shared-state.sh"
+
+SESSION="$AI_AGENTS_SESSION"
 
 usage() {
     cat <<EOF
@@ -75,12 +75,14 @@ while [[ $# -gt 0 ]]; do
 done
 
 # Format and write message
+ensure_shared_state_paths
+
 FORMATTED_MSG=$(format_message "$MSG_TYPE" "$AGENT_ID" "$MESSAGE")
-echo -e "$FORMATTED_MSG" >> "$SHARED_FILE"
+echo -e "$FORMATTED_MSG" >> "$AI_AGENTS_SHARED_FILE"
 
 # Also write plain text version for parsing
 TIMESTAMP=$(date '+%H:%M:%S')
-echo "[$TIMESTAMP] [$AGENT_ID] [$MSG_TYPE] $MESSAGE" >> "${SHARED_FILE}.log"
+echo "[$TIMESTAMP] [$AGENT_ID] [$MSG_TYPE] $MESSAGE" >> "${AI_AGENTS_SHARED_FILE}.log"
 
 # Desktop notification if requested
 if [[ "$DO_NOTIFY" == true ]]; then

diff --git a/kitty/scripts/ai-agent-send.sh b/kitty/scripts/ai-agent-send.sh
@@ -6,7 +6,10 @@
 
 set -euo pipefail
 
-SHARED_FILE="/tmp/ai-agents-shared.txt"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/lib/constants.sh"
+source "${SCRIPT_DIR}/lib/shared-state.sh"
+
 AGENT_ID="${1:-Unknown}"
 MESSAGE="${2:-}"
 
@@ -16,5 +19,7 @@ if [[ -z "$MESSAGE" ]]; then
     exit 1
 fi
 
+ensure_shared_state_paths
+
 TIMESTAMP=$(date '+%H:%M:%S')
-echo "[$TIMESTAMP] [$AGENT_ID] $MESSAGE" >> "$SHARED_FILE"
+echo "[$TIMESTAMP] [$AGENT_ID] $MESSAGE" >> "$AI_AGENTS_SHARED_FILE"
diff --git a/kitty/scripts/ai-compete-score.sh b/kitty/scripts/ai-compete-score.sh
@@ -5,11 +5,11 @@
 
 set -euo pipefail
 
-SESSION=${KITTY_AI_SESSION:-ai-agents}
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/lib/colors.sh"
+source "${SCRIPT_DIR}/lib/constants.sh"
 
-MODE_STATE="/tmp/ai-mode-${SESSION}/competition.json"
+MODE_STATE="$AI_AGENTS_STATE_COMPETITION"
 AGENT="${1:-}"
 CRITERION="${2:-}"
 POINTS="${3:-}"
@@ -76,7 +76,7 @@ else
 fi
 
 # Announce score
-cat >> /tmp/ai-agents-shared.txt <<EOF
+cat >> "$AI_AGENTS_SHARED_FILE" <<EOF
 
 ${AGENT_COLOR}─────────────────────────────────────────${RESET}
 ${COLOR}${SYMBOL} ${AGENT} - ${CRITERION^}: ${POINTS}/25 points${RESET}
@@ -95,7 +95,7 @@ AGENT2_SCORE=$(jq -r '.scores.Agent2' "$MODE_STATE")
 
 # If both have scores >= 100, competition is complete
 if [[ "$AGENT1_SCORE" -ge 100 || "$AGENT2_SCORE" -ge 100 ]]; then
-    cat >> /tmp/ai-agents-shared.txt <<EOF
+    cat >> "$AI_AGENTS_SHARED_FILE" <<EOF
 $(success_color "════════════════════════════════════════")
 $(success_color " 📊 All criteria scored!")
 $(success_color "════════════════════════════════════════")

diff --git a/kitty/scripts/ai-compete-submit.sh b/kitty/scripts/ai-compete-submit.sh
@@ -5,11 +5,11 @@
 
 set -euo pipefail
 
-SESSION=${KITTY_AI_SESSION:-ai-agents}
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/lib/colors.sh"
+source "${SCRIPT_DIR}/lib/constants.sh"
 
-MODE_STATE="/tmp/ai-mode-${SESSION}/competition.json"
+MODE_STATE="$AI_AGENTS_STATE_COMPETITION"
 AGENT="${1:-}"
 SOLUTION_PATH="${2:-}"
 EXPLANATION="${3:-}"
@@ -48,7 +48,7 @@ else
 fi
 
 # Announce submission
-cat >> /tmp/ai-agents-shared.txt <<EOF
+cat >> "$AI_AGENTS_SHARED_FILE" <<EOF
 
 ${AGENT_COLOR}▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓${RESET}
 ${AGENT_COLOR} 📤 ${AGENT} - Solution Submitted!${RESET}
@@ -77,7 +77,7 @@ AGENT2_SUB=$(jq -r '.submissions.Agent2' "$MODE_STATE")
 if [[ "$AGENT1_SUB" != "null" && "$AGENT2_SUB" != "null" ]]; then
     CHALLENGE=$(jq -r '.challenge' "$MODE_STATE")
 
-    cat >> /tmp/ai-agents-shared.txt <<EOF
+    cat >> "$AI_AGENTS_SHARED_FILE" <<EOF
 $(success_color "════════════════════════════════════════")
 $(success_color " ✅ Both solutions submitted!")
 $(success_color "════════════════════════════════════════")

diff --git a/kitty/scripts/ai-compete-winner.sh b/kitty/scripts/ai-compete-winner.sh
@@ -5,11 +5,11 @@
 
 set -euo pipefail
 
-SESSION=${KITTY_AI_SESSION:-ai-agents}
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/lib/colors.sh"
+source "${SCRIPT_DIR}/lib/constants.sh"
 
-MODE_STATE="/tmp/ai-mode-${SESSION}/competition.json"
+MODE_STATE="$AI_AGENTS_STATE_COMPETITION"
 WINNER="${1:-}"
 REASON="${2:-}"
 
@@ -56,7 +56,7 @@ else
 fi
 
 # Grand finale announcement
-cat >> /tmp/ai-agents-shared.txt <<EOF
+cat >> "$AI_AGENTS_SHARED_FILE" <<EOF
 
 $(success_color "★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★")
 $(success_color "★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★")

diff --git a/kitty/scripts/ai-consensus-agree.sh b/kitty/scripts/ai-consensus-agree.sh
@@ -5,11 +5,11 @@
 
 set -euo pipefail
 
-SESSION=${KITTY_AI_SESSION:-ai-agents}
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/lib/colors.sh"
+source "${SCRIPT_DIR}/lib/constants.sh"
 
-MODE_STATE="/tmp/ai-mode-${SESSION}/consensus.json"
+MODE_STATE="$AI_AGENTS_STATE_CONSENSUS"
 FINAL_DECISION="${1:-}"
 
 if [[ ! -f "$MODE_STATE" ]]; then
@@ -47,7 +47,7 @@ DURATION=$(($(date +%s) - $(date -d "$STARTED" +%s)))
 MINUTES=$((DURATION / 60))
 
 # Announce final agreement
-cat >> /tmp/ai-agents-shared.txt <<EOF
+cat >> "$AI_AGENTS_SHARED_FILE" <<EOF
 
 $(success_color "═══════════════════════════════════════")
 $(success_color " 🏆 FINAL AGREEMENT RECORDED")

diff --git a/kitty/scripts/ai-consensus-concern.sh b/kitty/scripts/ai-consensus-concern.sh
@@ -5,11 +5,11 @@
 
 set -euo pipefail
 
-SESSION=${KITTY_AI_SESSION:-ai-agents}
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/lib/colors.sh"
+source "${SCRIPT_DIR}/lib/constants.sh"
 
-MODE_STATE="/tmp/ai-mode-${SESSION}/consensus.json"
+MODE_STATE="$AI_AGENTS_STATE_CONSENSUS"
 AGENT="${1:-}"
 CONCERN="${2:-}"
 
@@ -32,7 +32,7 @@ else
 fi
 
 # Present concern
-cat >> /tmp/ai-agents-shared.txt <<EOF
+cat >> "$AI_AGENTS_SHARED_FILE" <<EOF
 
 ${AGENT_COLOR}▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼${RESET}
 ${AGENT_COLOR} ⚠️  ${AGENT} - Concern${RESET}

diff --git a/kitty/scripts/ai-consensus-propose.sh b/kitty/scripts/ai-consensus-propose.sh
@@ -5,11 +5,11 @@
 
 set -euo pipefail
 
-SESSION=${KITTY_AI_SESSION:-ai-agents}
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/lib/colors.sh"
+source "${SCRIPT_DIR}/lib/constants.sh"
 
-MODE_STATE="/tmp/ai-mode-${SESSION}/consensus.json"
+MODE_STATE="$AI_AGENTS_STATE_CONSENSUS"
 AGENT="${1:-}"
 PROPOSAL="${2:-}"
 
@@ -40,7 +40,7 @@ else
 fi
 
 # Present proposal
-cat >> /tmp/ai-agents-shared.txt <<EOF
+cat >> "$AI_AGENTS_SHARED_FILE" <<EOF
 
 ${AGENT_COLOR}╔═══════════════════════════════════════╗${RESET}
 ${AGENT_COLOR}║  💡 ${AGENT} - Proposal                ║${RESET}
@@ -61,7 +61,7 @@ NUM_PROPOSALS=$(jq '.proposals | length' "$MODE_STATE")
 info_color "   Total proposals: $NUM_PROPOSALS"
 
 if [[ $NUM_PROPOSALS -ge 2 ]]; then
-    cat >> /tmp/ai-agents-shared.txt <<EOF
+    cat >> "$AI_AGENTS_SHARED_FILE" <<EOF
 $(success_color "════════════════════════════════════════")
 $(success_color " ✅ Both agents have proposed!")
 $(success_color "════════════════════════════════════════")

diff --git a/kitty/scripts/ai-consensus-refine.sh b/kitty/scripts/ai-consensus-refine.sh
@@ -5,11 +5,11 @@
 
 set -euo pipefail
 
-SESSION=${KITTY_AI_SESSION:-ai-agents}
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/lib/colors.sh"
+source "${SCRIPT_DIR}/lib/constants.sh"
 
-MODE_STATE="/tmp/ai-mode-${SESSION}/consensus.json"
+MODE_STATE="$AI_AGENTS_STATE_CONSENSUS"
 REFINED_PROPOSAL="${1:-}"
 
 if [[ ! -f "$MODE_STATE" ]]; then
@@ -24,7 +24,7 @@ if [[ -z "$REFINED_PROPOSAL" ]]; then
 fi
 
 # Present refined proposal
-cat >> /tmp/ai-agents-shared.txt <<EOF
+cat >> "$AI_AGENTS_SHARED_FILE" <<EOF
 
 $(shared_color "╔═══════════════════════════════════════╗")
 $(shared_color "║  🔄 REFINED PROPOSAL                  ║")

diff --git a/kitty/scripts/ai-consensus-vote.sh b/kitty/scripts/ai-consensus-vote.sh
@@ -5,11 +5,11 @@
 
 set -euo pipefail
 
-SESSION=${KITTY_AI_SESSION:-ai-agents}
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/lib/colors.sh"
+source "${SCRIPT_DIR}/lib/constants.sh"
 
-MODE_STATE="/tmp/ai-mode-${SESSION}/consensus.json"
+MODE_STATE="$AI_AGENTS_STATE_CONSENSUS"
 AGENT="${1:-}"
 VOTE="${2:-}"
 
@@ -55,7 +55,7 @@ case "$VOTE" in
 esac
 
 # Announce vote
-cat >> /tmp/ai-agents-shared.txt <<EOF
+cat >> "$AI_AGENTS_SHARED_FILE" <<EOF
 
 $(shared_color "─────────────────────────────────────────")
 ${VOTE_COLOR}${SYMBOL} ${AGENT} votes: ${VOTE^^}${RESET}
@@ -80,7 +80,7 @@ if [[ "$AGENT1_VOTE" != "null" && "$AGENT2_VOTE" != "null" ]]; then
         jq '.consensus_reached = true' \
            "$MODE_STATE" > "${MODE_STATE}.tmp" && mv "${MODE_STATE}.tmp" "$MODE_STATE"
 
-        cat >> /tmp/ai-agents-shared.txt <<EOF
+        cat >> "$AI_AGENTS_SHARED_FILE" <<EOF
 
 $(success_color "★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★")
 $(success_color " 🤝 CONSENSUS REACHED!")
@@ -104,7 +104,7 @@ EOF
 
     else
         # No consensus
-        cat >> /tmp/ai-agents-shared.txt <<EOF
+        cat >> "$AI_AGENTS_SHARED_FILE" <<EOF
 
 $(warning_color "════════════════════════════════════════")
 $(warning_color " ⚠️  No Consensus Yet")