Danny Stocker 4d52d740d1 [AGENT-9] Final working tree cleanup - communication protocol and UI polish

- Add AGENT_COMMUNICATION_PROTOCOL.md (intra-agent messaging spec)
- Update client/tailwind.config.js (CSS refinements)
- Update feature-selector-complete.html (UI polish)

All artifacts ready for cloud session deployment.

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-13 11:03:39 +01:00

26 KiB

Raw Export PDF Permalink Blame History

Agent Communication Protocol

Cloud ↔ Local Machine Coordination Framework

Document Version: 1.0 Created: 2025-11-13 Last Updated: 2025-11-13 11:15 UTC Status: ACTIVE - Production Communication Framework

Executive Summary

This document defines how CLOUD agents (running 5 parallel sessions in Claude.com) communicate with the LOCAL machine (navidocs repository on home/setup) to coordinate work, request decisions, report blockers, and synchronize deployments.

Key Principles:

Asynchronous: Agents don't wait for responses; they check for updates every 5 minutes
Git-Native: All communication flows through git commits and files
GitHub-Backed: GitHub Issues provide high-visibility escalation path
Human-Transparent: Local machine (Danny) can see all agent requests at a glance
Fault-Tolerant: Network disconnects don't break workflow; agents resume from last checkpoint

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│ CLOUD ENVIRONMENT (Claude.com - 5 Parallel Sessions)       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Session 1 (Market Research)      Session 2 (Integration)   │
│  Agents S1-H01 to S1-H10           Agents S2-H0A to S2-H10  │
│  ↓ Read: AUTONOMOUS-NEXT-TASKS    ↓ Create: GitHub Issues   │
│  ↓ Commit: intelligence/session-1/ ↓ Commit: intelligence/   │
│  ↓ Push to origin                  ↓ Push to origin          │
│                                                              │
│  Session 3 (UX/Sales)              Session 4 (Planning)      │
│  Agents S3-H01 to S3-H10           Agents S4-H0A to S4-H10  │
│                                                              │
│  Session 5 (Validation)                                      │
│  Agents S5-H0A to S5-H10                                    │
│                                                              │
└──────────────────────────┬──────────────────────────────────┘
                           │
                    [Git Sync Every 5min]
                           │
       ┌───────────────────┼───────────────────┐
       ↓                   ↓                   ↓
   ┌─────────┐        ┌──────────┐      ┌──────────┐
   │   Git   │        │ GitHub   │      │  Files   │
   │ Remote  │        │  Issues  │      │  Sync    │
   │ (GitHub)│        │  (Alert) │      │  (Async) │
   └────┬────┘        └────┬─────┘      └────┬─────┘
        │                  │                 │
        └──────────────────┼─────────────────┘
                           │
┌──────────────────────────▼──────────────────────────┐
│ LOCAL MACHINE (Danny + Navidocs Repo)              │
├───────────────────────────────────────────────────┤
│                                                    │
│  📄 AUTONOMOUS-NEXT-TASKS.md (Agent instructions) │
│  🔔 GitHub Issues (Agent requests)                │
│  📁 intelligence/session-X/ (Agent outputs)       │
│  📋 AGENT_COMMUNICATION_PROTOCOL.md (this doc)    │
│                                                    │
│  Human Actions:                                    │
│  - Read agent status every 5 minutes               │
│  - Respond to GitHub issues with decisions        │
│  - Update AUTONOMOUS-NEXT-TASKS.md with new work  │
│  - Push changes (agents detect within 5 min)      │
│                                                    │
└────────────────────────────────────────────────────┘

Communication Channels

1. File-Based Communication (Primary)

File: AUTONOMOUS-NEXT-TASKS.md

Direction: Local → Cloud
Format: Markdown task list with agent assignments
Update Frequency: Every 5-30 minutes during active sessions
Cloud Poll Frequency: Every 5 minutes (git fetch + show)

How it works:

# Local machine updates task:
Danny: "Agent 2 needs to wait for Redis confirmation by 11:30"
→ Edit AUTONOMOUS-NEXT-TASKS.md, Agent 2 section
→ Commit: git commit -m "[AGENT-SYNC] Update Agent 2 Redis blocker"
→ Push: git push origin navidocs-cloud-coordination

# Cloud agent detects change:
Agent S2-H02: (every 5 minutes)
→ git fetch origin navidocs-cloud-coordination
→ git show origin:AUTONOMOUS-NEXT-TASKS.md
→ Parse Agent 2 section
→ Read: "Blocker: Waiting for Redis... Fallback: PostgreSQL"
→ Execute: Implement PostgreSQL fallback

Cloud Agent Polling Implementation:

#!/bin/bash
# Cloud agent polling script (runs every 5 minutes)
AGENT_ID="S2-H02"  # Agent 2
SESSION=2

while true; do
  git fetch origin navidocs-cloud-coordination
  CURRENT_TASK=$(git show origin:AUTONOMOUS-NEXT-TASKS.md | \
    grep -A 50 "## Agent 2:" | grep -m 1 "Status:")

  if [ "$CURRENT_TASK" != "$LAST_TASK" ]; then
    echo "New task detected: $CURRENT_TASK"
    # Execute new task...
  fi

  LAST_TASK="$CURRENT_TASK"
  sleep 300  # 5 minutes
done

2. GitHub Issues (Escalation + Visibility)

Template: .github/ISSUE_TEMPLATE/agent-ping.md

Direction: Cloud → Local (primary), Local → Cloud (response)
Format: Structured GitHub issue with agent details
Creation: When agent has BLOCKER or needs human decision
Resolution: Local machine closes with decision/action

When to Create GitHub Issue:

| Scenario | Create Issue? | Example | |----------|---------------|---------| | Status update (on track) | No | "Agent 1: 60% complete" | | Task blocked | YES | "Agent 2: Waiting for Redis response, need decision by 11:30" | | Needs decision | YES | "Agent 4: ProcessWire API unavailable, use scraper or wait?" | | Ready to deploy | YES | "Agent 1: Inventory system deploy-ready, approve staging?" | | Integration conflict | YES | "Agent 10: Data model mismatch between Agents 2 and 5" | | Query/clarification | YES | "Agent 3: Need property photos format (PNG vs WEBP)?" |

Issue Creation Flow:

Agent S2-H02 detects Redis blocker:
→ Title: "[AGENT-2] Redis availability confirmation needed"
→ Labels: agent-communication, blocker
→ Assigns to: [GitHub user - Danny/Coordinator]
→ Sets deadline: 2025-11-13 11:30 UTC

Danny (local) receives notification:
→ Reads issue details
→ Makes decision: "If no response by 11:30, use PostgreSQL"
→ Updates AUTONOMOUS-NEXT-TASKS.md Agent 2 section
→ Comments on issue: "Proceeding with PostgreSQL fallback"
→ Closes issue (agent sees closure = decision made)

Agent S2-H02 detects closed issue:
→ Pulls latest AUTONOMOUS-NEXT-TASKS.md
→ Sees: "Fallback: PostgreSQL caching"
→ Implements fallback
→ Reports completion in next status update

3. Git Commits (Status Signals)

Direction: Cloud → Local (one-way signal)

Format: Git commit messages with agent status codes
Frequency: When agent completes major milestone
Message Format: [SESSION-X-AGENT-N] Brief description of completion

Example Commit Messages:

[SESSION-2-AGENT-1] Photo inventory CRUD endpoints complete, OCR parsing 95% done
[SESSION-2-AGENT-2] Meilisearch index optimized, PostgreSQL cache layer active
[SESSION-2-AGENT-10] Integration tests passing, 2 minor conflicts resolved
[SESSION-1-ESCALATION] Market analysis >20% variance detected between agents

Local Machine Git Log Monitoring:

# Danny can see agent progress in git log
git log --oneline --decorate origin/navidocs-cloud-coordination | head -20

# Output:
# da1263d [SESSION-2-AGENT-1] Photo inventory CRUD endpoints complete
# 9f8c3a2 [SESSION-2-AGENT-0A] Helper agent: citation validation complete
# 8e7b1f5 [SESSION-2-AGENT-2] Meilisearch optimization in progress

4. File Sync (Agent Outputs)

Directory: intelligence/session-X/

Direction: Cloud → Local
Format: Markdown documents + JSON data files
Frequency: Generated when agents complete tasks
Polling by next agents: Every 5 minutes (check file existence)

Output Files per Session:

intelligence/
├── session-1/
│   ├── market-analysis.md              (Main findings)
│   ├── session-1-citations.json        (IF.TTT-compliant citations)
│   ├── session-1-handoff.md            (Ready for next session)
│   ├── QUALITY_FEEDBACK.md             (Session 5 validation notes)
│   └── logs/                           (Agent execution logs)
│
├── session-2/
│   ├── architecture.md                 (Technical design)
│   ├── integration-specs.md            (API contracts)
│   ├── session-2-handoff.md            (Ready for Session 4)
│   └── ESCALATION-[issue].md           (If blockers detected)
│
└── [session-3, 4, 5 similar structure]

Dependency Polling Pattern:

# Session 2 Agent 10 waits for Session 1 completion
# (every 5 minutes)
if [ -f "intelligence/session-1/session-1-handoff.md" ]; then
  echo "✅ Session 1 complete"
  # Read handoff and proceed with synthesis
else
  echo "⏳ Waiting for Session 1..."
  # Try again in 5 minutes
fi

Communication Workflows

Workflow 1: Normal Task Execution

t=0: Cloud agents read AUTONOMOUS-NEXT-TASKS.md (task assigned)
     ├─ Agent sees: "Status: DEPLOY-READY, Blockers: None"
     └─ Agent executes task (e.g., implement feature X)

t=30min: Agent completes task
         ├─ Creates intelligence/session-2/agent-1-output.md
         ├─ Commits: "[SESSION-2-AGENT-1] Task complete"
         ├─ Pushes to origin/navidocs-cloud-coordination
         └─ Continues polling for next task

t=35min: Local machine (Danny) detects completion
         ├─ Reads git log
         ├─ Verifies output files exist
         ├─ Updates AUTONOMOUS-NEXT-TASKS.md: "Status: ✅ COMPLETE"
         ├─ Commits update
         ├─ Pushes to origin
         └─ Unblocks dependent agents

t=40min: Dependent agents (Agent 10) detect unblock
         ├─ Polls AUTONOMOUS-NEXT-TASKS.md
         ├─ Sees: Agent 1 ✅ COMPLETE
         ├─ Reads intelligence/session-2/agent-1-output.md
         ├─ Proceeds with synthesis
         └─ [Cycle repeats]

Workflow 2: Blocker Resolution

t=0: Agent encounters blocker (Redis not installed)
     ├─ Updates AUTONOMOUS-NEXT-TASKS.md: "🔴 BLOCKED: Waiting for Redis"
     ├─ Creates GitHub Issue: "[AGENT-2] Redis confirmation needed by 11:30"
     ├─ Pushes to origin
     └─ Enters wait mode (retry polling every 5 min)

t=10min: Local machine (Danny) sees:
         ├─ Git notification: new issue created
         ├─ Reads GitHub issue details
         ├─ Decides: "Use PostgreSQL fallback"
         ├─ Comments on issue: "Proceed with PostgreSQL"
         ├─ Updates AUTONOMOUS-NEXT-TASKS.md:
         │  - "Status: 🟡 IN-PROGRESS"
         │  - "Fallback: PostgreSQL caching (line 95)"
         ├─ Closes GitHub issue (signals decision made)
         └─ Pushes update

t=15min: Agent detects:
         ├─ GitHub issue closed (decision made!)
         ├─ Polls AUTONOMOUS-NEXT-TASKS.md
         ├─ Reads: "Fallback: PostgreSQL caching"
         ├─ Implements fallback
         ├─ Continues with task
         └─ Reports completion in next commit

t=45min: Agent reports: "[SESSION-2-AGENT-2] PostgreSQL cache layer active"
         └─ Cycle continues...

Workflow 3: Escalation (Critical Issue)

t=0: Agent detects critical conflict
     ├─ Creates: intelligence/session-2/ESCALATION-data-model-conflict.md
     ├─ Details: "Agent 2 uses UUID, Agent 5 uses integer ID"
     ├─ Creates high-priority GitHub Issue: "[ESCALATION] Data model conflict"
     ├─ Sets P0 priority
     ├─ Tags issue: escalation, blocker
     └─ Enters halt mode (stops work until resolved)

t=5min: Local machine (Danny) receives:
        ├─ GitHub notification (P0 escalation)
        ├─ Reads ESCALATION-* file
        ├─ Reviews Agent 2 and 5 outputs
        ├─ Makes decision: "Use UUID everywhere"
        ├─ Updates AUTONOMOUS-NEXT-TASKS.md:
        │  - "Agent 5: Re-implement using UUID (see escalation resolution)"
        ├─ Renames: ESCALATION-* → RESOLVED-data-model-conflict.md
        ├─ Commits: "[ESCALATION-RESOLVED] UUID standardization"
        ├─ Comments on GitHub issue with decision
        └─ Closes issue

t=10min: Agent 5 detects:
         ├─ Polls AUTONOMOUS-NEXT-TASKS.md
         ├─ Sees: "RESOLVED-data-model-conflict.md"
         ├─ Reads resolution: "Use UUID everywhere"
         ├─ Re-implements using UUID
         ├─ Commits: "[SESSION-4-AGENT-5] Data model UUID compliance"
         └─ Resumes normal execution

t=60min: All agents synchronized on UUID standard
         └─ Session continues normally

File Naming Conventions

AUTONOMOUS-NEXT-TASKS.md

Structure: One section per agent, updated frequently

## Agent N: [Feature Name]
**Status:** ✅ COMPLETE | 🟡 IN-PROGRESS | 🟡 READY | 🔴 BLOCKED
**Last Update:** [timestamp]
**Owner:** [Session]-H[number]

### Current Tasks
- [x] Completed subtask
- [ ] In-progress subtask
- [ ] Blocked subtask

### Blockers
[What's preventing completion]

### Next Actions
[What agent should do]

### Token Budget Used
- Allocation: X tokens
- Current: Y tokens
- Remaining: Z tokens

Escalation Files

Pattern: intelligence/session-X/ESCALATION-[brief-description].md

When created: Agent detects critical issue When resolved: Renamed to RESOLVED-[brief-description].md Format:

# ESCALATION: [Issue Title]
**Agent:** [Session-Agent ID]
**Severity:** P0 | P1 | P2
**Created:** [timestamp]
**Deadline:** [timestamp]

## Problem
[Detailed description of issue]

## Impact
[Which agents blocked, which sessions affected]

## Proposed Solutions
1. [Option A with pros/cons]
2. [Option B with pros/cons]
3. [Option C with pros/cons]

## Recommendation
[Which option is best and why]

Agent Output Files

Pattern: intelligence/session-X/[agent-output-topic].md

Examples:

intelligence/session-1/market-analysis.md (Session 1, main analysis)
intelligence/session-2/architecture.md (Session 2, technical design)
intelligence/session-3/pitch-deck.md (Session 3, sales materials)
intelligence/session-2/agent-1-output.md (Specific agent output)

Structure:

# [Topic]
**Agent:** S[Session]-H[Agent]
**Created:** [timestamp]
**Status:** COMPLETE | IN-PROGRESS | DRAFT

## Executive Summary
[2-3 sentence overview]

## Findings
[Detailed results]

## Recommendations
[What to do with findings]

## Next Steps
[What Agent N+1 should do]

## Citations
[IF.TTT-compliant citations with SHA-256 hashes]

Handoff Files

Pattern: intelligence/session-X/session-X-handoff.md

Purpose: Session X declares completion; next session uses as starting point

Structure:

# Session X Handoff
**Session:** [X]
**Agents:** S[X]-H01 through S[X]-HN
**Duration:** [HH:MM]
**Token Cost:** $[cost]
**Status:** ✅ COMPLETE

## Key Findings
- [Finding 1 from Agent 1]
- [Finding 2 from Agent 2]
- [Synthesis from Agent 10]

## Deliverables
- [File 1 with location]
- [File 2 with location]
- [File 3 with location]

## Quality Metrics
- Evidence quality: X%
- Consensus: Y%
- Token efficiency: Z%

## For Next Session
[What Session Y should focus on or be aware of]

## Citations
[Complete citation list with IF.TTT compliance]

GitHub Issue Management

Issue Template: agent-ping.md

Location: .github/ISSUE_TEMPLATE/agent-ping.md

Auto-populated fields:

---
name: Agent Ping
about: Cloud agent needs local machine action
title: '[AGENT-N] Brief description'
labels: agent-communication
---

Required fields for cloud agents:

Agent ID: S[Session]-H[number]
Request Type: BLOCKER | QUESTION | DEPLOY-READY | STATUS-UPDATE | ESCALATION
Priority: P0 (CRITICAL) | P1 (HIGH) | P2 (MEDIUM) | P3 (LOW)
Deadline: When decision needed

Issue Labels

Label	Meaning	Auto-Close?
agent-communication	Standard agent ping	No (await response)
blocker	Agent cannot proceed	No (needs resolution)
escalation	Critical issue	No (needs human decision)
question	Agent needs clarification	No (needs answer)
deploy-ready	Feature ready to ship	No (needs approval)
resolved	Issue has been addressed	Yes (auto-close in 1hr)
on-track	Status update, no action needed	Yes (auto-close immediately)

Network Resilience

What Happens if GitHub is Unreachable?

Scenario: GitHub API down, but origin remote still accessible

Cloud Agent:
1. Attempt to create GitHub issue (FAILS)
2. Fall back to git-based communication:
   - Create file: intelligence/session-X/ISSUE-[id].md
   - Commit and push (uses git, not GitHub API)
3. Local machine still sees notification (git log updated)
4. When GitHub recovers, retry GitHub issue creation

Local Machine:
1. Can still poll via git fetch (doesn't require GitHub API)
2. Can still read AUTONOMOUS-NEXT-TASKS.md and respond
3. Can still read git commits and ISSUE files

What Happens if Network is Down?

Scenario: Temporary network outage

Cloud Agent:
1. Queues work locally (agent VM has disk storage)
2. Every 30 seconds: attempts git push
3. When network recovers: pushes all queued commits at once
4. No work is lost; just delayed

Local Machine:
1. Cannot poll for updates (no internet)
2. Agent work continues (independent operation)
3. When network recovers: Danny runs git pull
4. Sees all agent progress in git log
5. Can respond with new AUTONOMOUS-NEXT-TASKS.md

Integration Patterns

Pattern 1: Sequential Dependencies

Session 1 (Market Research)
    ↓ [Handoff file created]
Session 2 (Architecture)
    ↓ [Agents 0A-0D provide parallel support while waiting]
Session 3 + Session 4 (UX + Implementation)
    ↓ [Both depend on Sessions 1+2]
Session 5 (Validation)

How it works:

Session 1 Agent 10 creates intelligence/session-1/session-1-handoff.md
Session 2 Agents 1-9 poll every 5 min for handoff file
When file appears, Session 2 proceeds
Session 2 Agent 10 creates its own handoff
Sessions 3 + 4 poll for Session 2 handoff
Continue pattern...

Pattern 2: Parallel Support (Helper Agents)

Session 2 Agents 0A, 0B, 0C, 0D (Helper Agents)
    ↓
Assist Session 1 (validation, citations, web scraping)
    ↓
When Session 1 complete, assist Session 3
    ↓
Cross-session quality and progress monitoring

How it works:

Helper agents check AUTONOMOUS-NEXT-TASKS.md every 5 min
Identify sessions needing support
Provide targeted assistance (validation, citations, research)
Report findings back to main agents
Continue until all sessions complete

Pattern 3: Quality Feedback Loop

Session 5 Agent 0B (Quality Monitoring)
    ↓
Polls intelligence/session-1/, session-2/, session-3/, session-4/
    ↓
Detects quality issues (missing citations, etc.)
    ↓
Creates QUALITY_FEEDBACK.md (updated every 5 min)
    ↓
Sessions 1-4 detect feedback
    ↓
Fix issues proactively (don't wait for final validation)

How it works:

Session 5 Agent 0B commits QUALITY_FEEDBACK.md every 5 minutes
Sessions 1-4 poll for QUALITY_FEEDBACK.md every 5 minutes
If feedback detected, fix issues immediately
Re-commit fixed files
Session 5 Agent 0B verifies fixes in next feedback round
Continuous quality improvement (doesn't wait for end)

Monitoring Dashboard

For Local Machine (Danny)

Check every 5 minutes:

# Show agent status summary
git log --oneline origin/navidocs-cloud-coordination | head -10

# Show open agent pings (GitHub issues)
gh issue list --state=open --label=agent-communication

# Show escalations
ls -la intelligence/session-*/ESCALATION-*.md 2>/dev/null || echo "No escalations"

# Show task status
git show origin:AUTONOMOUS-NEXT-TASKS.md | grep "Status:" | head -10

For Cloud Agents

Check every 5 minutes:

# Get latest task assignments
git fetch origin navidocs-cloud-coordination
TASKS=$(git show origin:AUTONOMOUS-NEXT-TASKS.md)

# Parse your agent section
MY_AGENT="Agent 2"
MY_SECTION=$(echo "$TASKS" | grep -A 30 "## $MY_AGENT:")

# Extract status
STATUS=$(echo "$MY_SECTION" | grep "Status:" | sed 's/.*Status: //')
BLOCKERS=$(echo "$MY_SECTION" | grep -A 10 "Blockers" | head -5)

# Check for escalations
ESCALATIONS=$(git show origin:intelligence/session-2/ 2>/dev/null | \
  grep -l "ESCALATION" || echo "none")

Security & Access Control

Git Branch Access

Branch: navidocs-cloud-coordination

Push Access: Cloud sessions (automated), Local machine (Danny)
Pull Access: Public (anyone can read)
Protection: Branch protection enabled (no force push)

GitHub Issue Access

Labels: agent-communication

Create: Cloud agents (automated), Local machine
Comment: Cloud agents, Local machine, Reviewers
Close: Only Local machine (signals decision made)

File Permissions

File	Read	Write	Why
AUTONOMOUS-NEXT-TASKS.md	All	Local only	Controls what agents do
intelligence/session-X/*.md	All	Cloud agents	Agent outputs
ESCALATION-*.md	All	Cloud agents	Issue escalation
RESOLVED-*.md	All	Local only	Marks escalation resolved

Troubleshooting

Agent Not Detecting Updates

Symptom: Agent still executing old task after 10 minutes

Diagnosis:

Check if git fetch succeeded: git fetch origin navidocs-cloud-coordination
Verify file was updated: git show origin:AUTONOMOUS-NEXT-TASKS.md | grep "## Agent [N]:" -A 5
Check agent polling loop: Is it running? Check process list

Solution:

Force re-read: git fetch --force origin
Kill and restart agent process
Create manual GitHub issue to wake agent up

GitHub Issue Not Created

Symptom: Agent attempted to create issue but it doesn't appear

Diagnosis:

Check if GitHub API is accessible: curl https://api.github.com
Check authentication: gh auth status
Verify rate limit: gh api /rate_limit

Solution:

If API down: Fall back to git-based ISSUE-*.md files
If auth failed: Re-authenticate: gh auth login
If rate limited: Wait 60 minutes, retry

Merge Conflicts in AUTONOMOUS-NEXT-TASKS.md

Symptom: Push fails with merge conflict

Diagnosis:

Danny and agent both edited file simultaneously
Agent edited old version, Danny updated newer version

Solution:

Agent: git pull origin navidocs-cloud-coordination
Agent: Resolve conflicts (keep Danny's latest edits + your new edits)
Agent: git add AUTONOMOUS-NEXT-TASKS.md && git commit && git push
Danny: Verify resolution looks correct

Escalation File Not Detected

Symptom: Agent created ESCALATION-*.md but local machine didn't notice

Diagnosis:

Check if file exists: ls intelligence/session-X/ESCALATION-*
Check if git tracked it: git log -- intelligence/session-X/ESCALATION-*
Verify remote has it: git ls-tree -r origin:intelligence/session-X/

Solution:

Agent: git add intelligence/session-X/ESCALATION-*.md && git commit && git push
Local: git pull origin navidocs-cloud-coordination
Local: Verify with git ls-tree -r origin:intelligence/session-X/

Appendix: Command Reference

Local Machine Commands

# Monitor agent progress
watch -n 300 'git log --oneline origin/navidocs-cloud-coordination | head -10'

# See all agent GitHub issues
gh issue list --state=open --label=agent-communication -R dannystocker/navidocs

# Update tasks for all agents
# (Edit AUTONOMOUS-NEXT-TASKS.md, then:)
git add AUTONOMOUS-NEXT-TASKS.md
git commit -m "[AGENT-SYNC] Update task status for Agents 1-10"
git push origin navidocs-cloud-coordination

# View complete session outputs
ls intelligence/session-*/

# Check for escalations
find intelligence/session-*/ -name "ESCALATION-*"

Cloud Agent Commands

# Poll for task updates (every 5 minutes)
git fetch origin navidocs-cloud-coordination
git show origin:AUTONOMOUS-NEXT-TASKS.md | grep "## Agent [N]:" -A 30

# Commit completion
git add intelligence/session-X/my-output.md
git commit -m "[SESSION-X-AGENT-N] Task complete: [brief description]"
git push origin navidocs-cloud-coordination

# Check for escalation resolutions
git show origin:intelligence/session-X/RESOLVED-*.md

# Create backup if no network
git add . && git commit -m "[OFFLINE] Local checkpoint: [description]"
# (When network recovers: git push)

Document Maintenance

Owner: Local Machine Coordinator (Danny) Review Frequency: Every session (every 2-3 hours) Update Triggers:

New escalation pattern discovered
Communication failure
Process improvement
New integration pattern

Version History:

v1.0 (2025-11-13): Initial framework, 5-session coordination

Status: ACTIVE - Ready for cloud ↔ local coordination Last Updated: 2025-11-13 11:15 UTC Next Review: 2025-11-13 after Session 1 launches

26 KiB Raw Export PDF Permalink Blame History Unescape Escape

Agent Communication Protocol

Executive Summary

Architecture Overview

Communication Channels

1. File-Based Communication (Primary)

2. GitHub Issues (Escalation + Visibility)

3. Git Commits (Status Signals)

4. File Sync (Agent Outputs)

Communication Workflows

Workflow 1: Normal Task Execution

Workflow 2: Blocker Resolution

Workflow 3: Escalation (Critical Issue)

File Naming Conventions

AUTONOMOUS-NEXT-TASKS.md

Escalation Files

Agent Output Files

Handoff Files

GitHub Issue Management

Issue Template: agent-ping.md

Issue Labels

Network Resilience

What Happens if GitHub is Unreachable?

What Happens if Network is Down?

Integration Patterns

Pattern 1: Sequential Dependencies

Pattern 2: Parallel Support (Helper Agents)

Pattern 3: Quality Feedback Loop

Monitoring Dashboard

For Local Machine (Danny)

For Cloud Agents

Security & Access Control

Git Branch Access

GitHub Issue Access

File Permissions

Troubleshooting

Agent Not Detecting Updates

GitHub Issue Not Created

Merge Conflicts in AUTONOMOUS-NEXT-TASKS.md

Escalation File Not Detected

Appendix: Command Reference

Local Machine Commands

Cloud Agent Commands

Document Maintenance

26 KiB

Raw Export PDF Permalink Blame History