Workspace Structure

Purpose

Workspace directory conventions — projects as containers, entities belong to projects, SBX as infrastructure

Rules

WSP-001: SBX is infrastructure tool (like git, docker). Lives in .framework/. Not a domain entity.

Infrastructure confusion causes governance violations. SBX manages entities — it is not one. Placing it in .framework/ keeps it separate from workspace data.

Verification: Directory check: .framework/ contains framework code, not domain entities.

WSP-002: Projects are operational containers. Live at projects/{name}/.

Projects are the primary organizational unit. Consistent location enables scanning and CLI discovery.

Verification: CLI check: sbx project list discovers all projects from workspace/projects/.

WSP-003: Entities are properties of projects, not workspace-level peers. Live at projects/{name}/entities/.

Entity containment prevents orphaned entities and enables cascade operations (delete project → delete entities).

Verification: No entity directories exist at workspace root level. All entities nested under a project.

WSP-004: Project contains: project.yml, entities/, components/, features/, research/.

Standard project structure enables tooling to scan any project with the same expectations. Predictable layout reduces cognitive load.

Verification: Project scaffold: sbx project create produces all required subdirectories.

WSP-005: Entity defines WHAT (domain model). Component tracks HOW (development status).

Separating definition (entity) from implementation tracking (component) prevents model pollution with process state.

Verification: Entity YAML has no status/progress fields. Component YAML tracks implementation state.

Tags

Overview