Workspace Layout Reference

Overview

This document provides non-normative examples of standard OpenStandardAgents directory structures and layout configurations within Bluefly. It serves as a visual guide and reference (No SHALL/MUST constraints are defined here; for normative constraints, see the architecture and standard documents).

Scope note (2026-08-27): Examples below use NAS/Mac paths from the dev-client layout (ADR-0006). Production Gas City uses Oracle-local paths (/opt/bluefly/blucity, /opt/bluefly/rigs/<rig>) and Tailscale operator access — see oracle-canonical-architecture.

Example Workspace Layout

A typical Bluefly engineering environment containing the composition root and project contracts:

/Volumes/AgentPlatform/
├── .agents-workspace/               # Workspace Composition Root (OSSA Control Plane)
│   ├── workspace.yaml
│   ├── bindings/
│   └── topology/
├── .gc/                             # Generated Machine-Local Runtime State (Ephemeral)
│   ├── resolution.json
│   └── active-bindings/
├── project-alpha/
│   ├── src/
│   └── .agents/                     # Project-Level Agent Contract
│       ├── project.yaml
│       ├── registry.yaml
│       ├── bindings/
│       └── policies/
└── project-beta/
    ├── package.json
    └── .agents/
        ├── project.yaml
        ├── registry.yaml
        ├── skills/
        └── workflows/

Example project.yaml

version: 1.0
kind: AgentContract
metadata:
  name: project-alpha
  owner: core-engineering
capabilities:
  - id: analyze-logs
    type: diagnostic

Example workspace.yaml

version: 1.0
kind: WorkspaceComposition
metadata:
  name: bluefly-core-workspace
bindings:
  - target: project-alpha
    source: path/to/project-alpha/.agents
  - target: project-beta
    source: path/to/project-beta/.agents
packs:
  - id: diagnostic-pack-v2
    version: ~2.1.0