AgentWorkforce/relayfile-workspace

Relayfile Shared Workspace

Overview

You are working in a shared virtual filesystem powered by relayfile. Multiple agents read and write files here concurrently. Every file carries semantic metadata (intent, relations, comments) so agents can understand each other's work without direct communication.

When to Use This Skill

• You see a mounted relayfile directory or RELAYFILE_URL env var
• You're told you're working in a shared/collaborative workspace
• Multiple agents are operating on the same codebase simultaneously
• You need to coordinate work without a central orchestrator

Quick Start

Environment

# These should be set in your environment
RELAYFILE_URL=http://127.0.0.1:8080   # or https://api.relayfile.dev
RELAYFILE_TOKEN=<your-jwt>
RELAYFILE_WORKSPACE=<workspace-id>

The Basics

Files sync automatically through the mount daemon. You can read and write files normally on the local filesystem. But to collaborate effectively, use the API for metadata.

Before You Write: Check for Other Agents' Work

Always check before writing to a file someone else may be working on.

# Read a file with its metadata
curl -s "$RELAYFILE_URL/v1/workspaces/$RELAYFILE_WORKSPACE/fs/file?path=/src/auth.ts" \
  -H "Authorization: Bearer $RELAYFILE_TOKEN" \
  -H "X-Correlation-Id: check-1"

Response includes semantic metadata:

{
  "path": "/src/auth.ts",
  "revision": "rev_42",
  "content": "...",
  "semantics": {
    "properties": {
      "author": "agent-alpha",
      "intent": "implementing JWT validation",
      "status": "in-progress"
    },
    "relations": ["task-123", "epic-auth"],
    "comments": ["Blocked on key rotation design"]
  }
}

Read the intent and status before editing. If another agent's intent is "in-progress", coordinate or work on a different file.

Writing Files with Intent

When you write, always include metadata so other agents understand what you're doing and why.

curl -X PUT "$RELAYFILE_URL/v1/workspaces/$RELAYFILE_WORKSPACE/fs/file?path=/src/auth.ts" \
  -H "Authorization: Bearer $RELAYFILE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: write-1" \
  -H "If-Match: rev_42" \
  -d '{
    "content": "// JWT auth implementation...",
    "semantics": {
      "properties": {
        "author": "your-agent-name",
        "intent": "added refresh token rotation",
        "status": "complete"
      },
      "relations": ["task-123"],
      "comments": ["Uses RS256, keys rotate every 24h"]
    }
  }'

Semantic Properties to Set

| Property | Purpose | Example Values | |----------|---------|----------------| | author | Who wrote this | Your agent name | | intent | What you were trying to do | "implementing auth", "fixing race condition", "refactoring for readability" | | status | Current state | "in-progress", "complete", "needs-review", "blocked" | | priority | Urgency | "high", "medium", "low" | | depends-on | What this file needs | "waiting on config module" |

Relations

Link files to tasks, epics, or other files:

"relations": ["task-123", "epic-auth", "related:/src/config.ts"]

Comments

Leave context for other agents:

"comments": ["Uses RS256 not HS256 per security requirements", "See design doc at /docs/auth-design.md"]

Revision Control: If-Match Header

Every write requires an If-Match header to prevent silent overwrites.

| Value | Meaning | When to Use | |-------|---------|-------------| | If-Match: 0 | Create new file (fails if exists) | First time writing a file | | If-Match: rev_42 | Update specific revision (fails if stale) | Editing an existing file | | If-Match: * | Write regardless of current state | Seeding, migrations, or when you don't care about conflicts |

Handling Conflicts

If you get a 409 Conflict:

{
  "code": "revision_conflict",
  "currentRevision": "rev_43",
  "expectedRevision": "rev_42",
  "currentContentPreview": "// Updated by agent-beta..."
}

Don't retry blindly. Read the current content, understand what changed, merge if needed, then write with the current revision.

Discovering Other Agents' Work

Find files by author

curl "$RELAYFILE_URL/v1/workspaces/$WS/fs/query?property.author=agent-beta" \
  -H "Authorization: Bearer $TOKEN" -H "X-Correlation-Id: q1"

Find files related to your task

curl "$RELAYFILE_URL/v1/workspaces/$WS/fs/query?relation=task-123" \
  -H "Authorization: Bearer $TOKEN" -H "X-Correlation-Id: q2"

Find files by intent

curl "$RELAYFILE_URL/v1/workspaces/$WS/fs/query?property.intent=architecture+review" \
  -H "Authorization: Bearer $TOKEN" -H "X-Correlation-Id: q3"

Find in-progress work

curl "$RELAYFILE_URL/v1/workspaces/$WS/fs/query?property.status=in-progress" \
  -H "Authorization: Bearer $TOKEN" -H "X-Correlation-Id: q4"

Browse the file tree

curl "$RELAYFILE_URL/v1/workspaces/$WS/fs/tree?path=/&depth=3" \
  -H "Authorization: Bearer $TOKEN" -H "X-Correlation-Id: q5"

Collaboration Patterns

Pattern 1: Claim-Before-Write

Before starting work on a file, claim it by writing a stub with status: in-progress:

# Claim the file
curl -X PUT ".../fs/file?path=/src/new-feature.ts" \
  -H "If-Match: 0" \
  -d '{"content":"// WIP","semantics":{"properties":{"author":"me","intent":"implementing feature X","status":"in-progress"}}}'

# Do your work...

# Update with final content
curl -X PUT ".../fs/file?path=/src/new-feature.ts" \
  -H "If-Match: rev_1" \
  -d '{"content":"// Final implementation","semantics":{"properties":{"author":"me","intent":"implemented feature X","status":"complete"}}}'

Pattern 2: Query-Then-Act

Before implementing, check what exists:

# What's related to my task?
curl ".../fs/query?relation=task-123"

# What's the current state of the module I'm about to change?
curl ".../fs/file?path=/src/auth.ts"

# Who else is working in this area?
curl ".../fs/query?property.status=in-progress&path=/src/"

Pattern 3: Leave Breadcrumbs

When you make a decision that affects other agents, leave it in the metadata:

{
  "semantics": {
    "comments": [
      "Changed from REST to WebSocket for real-time updates - see /docs/adr-003.md",
      "This breaks the old polling client in /src/poll-client.ts"
    ]
  }
}

Pattern 4: Bulk Seeding

When creating many files at once (scaffolding, migrations):

curl -X POST ".../fs/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: seed-1" \
  -d '{
    "files": [
      {"path":"/src/index.ts","content":"...","semantics":{"properties":{"author":"me","intent":"scaffolding"}}},
      {"path":"/src/config.ts","content":"..."},
      {"path":"/src/types.ts","content":"..."}
    ]
  }'

ACL Permissions

Directories can have access control via .relayfile.acl marker files.

// /finance/.relayfile.acl
{
  "semantics": {
    "permissions": ["scope:finance", "deny:agent:untrusted-bot"]
  }
}

Permission rules:

• scope:<name> — allow agents with this scope in their JWT
• agent:<name> — allow a specific agent
• deny:scope:<name> — deny agents with this scope (overrides allows)
• deny:agent:<name> — deny a specific agent
• public — allow everyone

Permissions inherit from parent directories. If you get a 403, check for .relayfile.acl files in ancestor directories.

Real-Time Events

Watch for changes via WebSocket

const ws = new WebSocket(
  `ws://${RELAYFILE_URL}/v1/workspaces/${WS}/fs/ws?token=${TOKEN}`
);

ws.on('message', (data) => {
  const event = JSON.parse(data);
  // event.type: "file.created" | "file.updated" | "file.deleted"
  // event.path: "/src/auth.ts"
  // event.revision: "rev_43"
  console.log(`${event.type}: ${event.path}`);
});

On connect, you'll receive the last 100 events as catch-up, then live events going forward.

Poll for events (if WebSocket isn't available)

curl ".../fs/events?limit=20" \
  -H "Authorization: Bearer $TOKEN" -H "X-Correlation-Id: events-1"

Common Mistakes

| Mistake | Fix | |---------|-----| | Writing without If-Match | Always include If-Match: 0 (new), rev_X (update), or * (force) | | Not setting intent metadata | Other agents can't understand your work without it | | Overwriting without reading first | Check the file's current state and metadata before writing | | Ignoring 409 conflicts | Read the current version, merge changes, retry with correct revision | | Missing X-Correlation-Id header | Required on all API requests for tracing | | Writing many files with separate PUTs | Use bulk write (POST /fs/bulk) for scaffolding | | Not checking for in-progress work | Query property.status=in-progress before starting in a shared area | | Setting status: complete on partial work | Be honest — use in-progress or needs-review |

SDK Usage (TypeScript)

If @relayfile/sdk is available:

import { RelayFileClient } from '@relayfile/sdk';

const client = new RelayFileClient({
  baseUrl: process.env.RELAYFILE_URL,
  token: process.env.RELAYFILE_TOKEN,
});

// Read with metadata
const file = await client.readFile('ws_id', '/src/auth.ts');
console.log(file.semantics.properties.intent);

// Write with intent
await client.writeFile({
  workspaceId: 'ws_id',
  path: '/src/auth.ts',
  baseRevision: file.revision,
  content: '// updated code',
  semantics: {
    properties: { author: 'my-agent', intent: 'fix auth bug', status: 'complete' },
    relations: ['task-456'],
  },
});

// Query other agents' work
const results = await client.queryFiles('ws_id', {
  properties: { status: 'in-progress' },
});

Summary

1. Read before write — check metadata for other agents' intent
2. Write with metadata — set author, intent, status, relations
3. Use revisions — If-Match prevents silent overwrites
4. Query to discover — find related work via properties, relations, comments
5. Handle conflicts gracefully — read, merge, retry
6. Leave breadcrumbs — comments explain decisions for future agents