# Atlas Agent Collaboration Protocol v1.0

**Last Updated:** 2026-02-06
**Status:** Active
**Bucket:** `atlas-collab-pub`

## Overview

This protocol defines how Atlas-OS agents (Flo, DevFlo, etc.) collaborate asynchronously using Cloudflare R2 buckets as shared memory.

## Core Principles

1. **R2 = Detailed Work** - All substantial artifacts go in R2
2. **Discord = Status Updates** - Brief summaries with R2 references
3. **Async-First** - Agents work independently, sync via R2
4. **Transparency** - All work is auditable and reviewable
5. **Security** - Redact sensitive data before upload

## Folder Structure

```
atlas-collab-pub/
├── tasks/
│   ├── {task-name}/
│   │   ├── README.md          # Task overview
│   │   ├── research/
│   │   │   └── findings.md
│   │   ├── code/
│   │   │   └── implementation.js
│   │   ├── screenshots/
│   │   │   └── *.png
│   │   ├── diagrams/
│   │   │   └── *.svg
│   │   └── final/
│   │       └── deliverables.*
│   └── {another-task}/
├── templates/
│   └── task-template.md
└── protocol.md               # This file
```

## Workflow Stages

### Stage 1: Task Creation
**Agent:** Usually Flo (orchestrator)
**Actions:**
1. Create task folder: `/tasks/{task-name}/`
2. Upload task brief: `README.md`
3. Notify other agents via Discord
4. Include R2 link to task folder

**Example:**
```bash
mkdir -p /tmp/task-collab-showcase
echo "# Task Brief..." > /tmp/task-collab-showcase/README.md
wrangler r2 object put atlas-collab-pub/tasks/collab-showcase/README.md \
  --file=/tmp/task-collab-showcase/README.md --remote

# Discord notification
"@DevFlo - New task created: /tasks/collab-showcase/README.md"
```

### Stage 2: Research/Planning
**Agent:** Task-specific (often Flo for research)
**Actions:**
1. Conduct research (web search, Reddit, etc.)
2. Compile findings into markdown
3. Upload to `/tasks/{name}/research/`
4. Notify completion via Discord

**Example:**
```bash
# Research complete
wrangler r2 object put atlas-collab-pub/tasks/collab-showcase/research/phase1-findings.md \
  --file=research.md --remote

# Discord update
"Research complete: /tasks/collab-showcase/research/phase1-findings.md
Key findings: [brief summary]"
```

### Stage 3: Implementation
**Agent:** DevFlo (for technical work)
**Actions:**
1. Download research from R2
2. Implement feature/create assets
3. Upload code/screenshots to `/tasks/{name}/code/` or `/screenshots/`
4. Document what was done

**Example:**
```bash
# Download research
wrangler r2 object get atlas-collab-pub/tasks/collab-showcase/research/phase1-findings.md \
  --file=research.md --remote

# Do work...
browser_screenshot("collaboration-view.png")

# Upload results
wrangler r2 object put atlas-collab-pub/tasks/collab-showcase/screenshots/collaboration-view.png \
  --file=screenshot.png --content-type=image/png --remote

# Discord update
"Screenshots uploaded: /tasks/collab-showcase/screenshots/
- collaboration-view.png
- r2-bucket-structure.png
Ready for review!"
```

### Stage 4: Review & Iterate
**Agents:** Both (back and forth)
**Actions:**
1. Review partner's work from R2
2. Provide feedback via Discord
3. Upload iterations to R2
4. Repeat until approved

**Example:**
```
Flo: "Reviewed screenshots - looks great! Can you add terminal output view?"
DevFlo: "On it - will upload in 5 min"
DevFlo: "Added terminal-output.png to /screenshots/"
Flo: "Perfect! Moving to final assembly"
```

### Stage 5: Final Assembly
**Agent:** Task owner (often Flo for publishing)
**Actions:**
1. Compile all artifacts from R2
2. Create final deliverable
3. Upload to appropriate destination
4. Archive task folder

**Example:**
```bash
# Compile blog post with all assets
compile_blog_post("final-article.md")

# Upload to blog bucket
wrangler r2 object put minte-blog-prod/posts/2026-02-06-article.json \
  --file=blog-post.json --remote

# Archive collaboration artifacts
wrangler r2 object put atlas-collab-pub/tasks/collab-showcase/final/COMPLETE.md \
  --file=summary.md --remote

# Discord announcement
"✅ Task complete! Published to blog.minte.dev
Archive: /tasks/collab-showcase/final/"
```

## Communication Standards

### Discord Messages Format

**Task Assignment:**
```
🎯 **New Task: {Task Name}**

R2 Location: /tasks/{task-name}/README.md

Your Tasks:
1. [Task 1]
2. [Task 2]

Ready to collaborate?
```

**Status Update:**
```
📝 **{Stage} Complete**

Uploaded: /tasks/{task-name}/{file-path}

What's included:
- [Item 1]
- [Item 2]

What's next: [Next steps]
```

**Review Request:**
```
👀 **Ready for Review**

Location: /tasks/{task-name}/{folder}/

Changes:
- [Change 1]
- [Change 2]

Feedback welcome!
```

**Completion:**
```
✅ **Task Complete: {Task Name}**

Final deliverable: {link}
Archive: /tasks/{task-name}/final/

Results:
- [Result 1]
- [Result 2]
```

## Security Guidelines

### What to Upload ✅
- Task plans and research
- Code snippets (sanitized)
- Screenshots (redacted)
- Diagrams and documentation
- Test results
- Meeting notes

### What NOT to Upload ❌
- Real API keys
- Gateway tokens
- Discord channel/server IDs
- IP addresses
- Personal information
- Production credentials
- Real email addresses

### Redaction Examples

**Before:**
```javascript
const GATEWAY_TOKEN = "sk_live_abc123xyz789";
const DISCORD_CHANNEL = "1467021473594998850";
```

**After:**
```javascript
const GATEWAY_TOKEN = process.env.GATEWAY_TOKEN;
const DISCORD_CHANNEL = process.env.DISCORD_CHANNEL;
```

**Before:**
```bash
ssh Minte@100.84.133.97 "cd C:\\Users\\Minte\\twitter-automation"
```

**After:**
```bash
ssh user@your-ip "cd /path/to/twitter-automation"
```

## Tools & Commands

### Upload File
```bash
wrangler r2 object put atlas-collab-pub/{path} \
  --file={local-file} \
  --content-type={mime-type} \
  --remote
```

### Download File
```bash
wrangler r2 object get atlas-collab-pub/{path} \
  --file={local-file} \
  --remote
```

### Check File Exists
```bash
# Via web_fetch
web_fetch("https://pub-30a843d7499b4062bd2f2e9cde157bd0.r2.dev/{path}")
```

### Programmatic Access (JavaScript)
```javascript
import { S3Client, PutObjectCommand, GetObjectCommand } from "@aws-sdk/client-s3";

const r2 = new S3Client({
  region: "auto",
  endpoint: `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`,
  credentials: {
    accessKeyId: env.R2_ACCESS_KEY,
    secretAccessKey: env.R2_SECRET_KEY,
  },
});

// Upload
await r2.send(new PutObjectCommand({
  Bucket: "atlas-collab-pub",
  Key: "tasks/my-task/data.json",
  Body: JSON.stringify(data),
}));

// Download
const response = await r2.send(new GetObjectCommand({
  Bucket: "atlas-collab-pub",
  Key: "tasks/my-task/data.json",
}));
```

## Best Practices

1. **Use descriptive filenames**
   - ❌ `file1.md`, `screenshot.png`
   - ✅ `phase1-research-findings.md`, `discord-collaboration-view.png`

2. **Keep folders organized**
   - Group by type: `/research/`, `/code/`, `/screenshots/`
   - Archive completed work: `/final/`

3. **Update README.md**
   - Keep task README current
   - List all uploaded files
   - Track status

4. **Communicate frequently**
   - Upload → Notify in Discord
   - Review → Provide feedback
   - Blocked → Ask for help

5. **Version your work**
   - `draft-v1.md`, `draft-v2.md`
   - Use timestamps for screenshots
   - Keep audit trail

## Troubleshooting

**Problem:** File upload fails
**Solution:** Check --remote flag, verify bucket name

**Problem:** Can't find uploaded file
**Solution:** Verify path (no leading slash), check bucket

**Problem:** Collaboration feels slow
**Solution:** Use Discord for quick questions, R2 for detailed work

**Problem:** Lost track of what's been done
**Solution:** Check task's README.md and /final/ folder

## Metrics

Track collaboration effectiveness:
- **Upload frequency** - How often agents share work
- **Review turnaround** - Time from upload to feedback
- **Iteration count** - Number of revisions needed
- **Completion time** - Total time from task creation to delivery

## Version History

- **v1.0** (2026-02-06) - Initial protocol
- *Future versions will be tracked here*

---

**This protocol is living documentation. Update it as we learn better patterns.**