package ownership

Package Ownership & Decision Tree (for AI Assistants)

Moved from CLAUDE.md to reduce context size. Consult when deciding where to put code.

ALL shared code MUST be in the appropriate @bluefly/* packages. NO EXCEPTIONS.

See architecture/separation-of-duties.md for the complete ownership matrix.

Key Package Ownership Rules

Package	Owns	FORBIDDEN
`@bluefly/agent-brain`	Vector search, semantic search, Qdrant, embeddings, RAG, codebase indexing, memories	Creating vector/search services in other projects
`@bluefly/agent-docker`	Docker operations, Kubernetes operations, container management, deployment orchestration	Creating docker/kubernetes services in agent-buildkit
`@bluefly/agent-mesh`	Agent-to-agent communication, service mesh, coordination, discovery, transport, auth	Creating mesh/coordination services in agent-buildkit
`@bluefly/agent-protocol`	MCP servers, MCP registry, protocol adapters, MCP integration	Creating MCP/protocol services in agent-buildkit
`@bluefly/agent-router`	Agent routing, cost-aware routing, task routing, agent discovery, Vast.ai scaling	Creating router services in agent-buildkit
`@bluefly/agent-tailscale`	ALL Tailscale operations (subnet, DNS, SSH, certificates, webhooks, monitoring)	Creating ANY Tailscale services in agent-buildkit
`@bluefly/agent-tracer`	Distributed tracing, OpenTelemetry, RPC tracing, trace analysis, observability	Creating tracing services in agent-buildkit
`@bluefly/agentic-flows`	Agent orchestration, multi-agent workflows, service registry, ecosystem orchestration	Creating orchestration services in agent-buildkit
`@bluefly/compliance-engine`	Audit services, compliance checks, policy validation, separation of duties validation	Creating audit/compliance services in agent-buildkit (48 files found - MIGRATE!)
`@bluefly/foundation-bridge`	LLM providers, model orchestration, provider routing, enterprise LLM services	Creating LLM provider services in agent-buildkit
`@bluefly/workflow-engine`	Workflow execution, state management, step runners, error handling, workflow types	Creating workflow services in agent-buildkit (8 files found - MIGRATE!)
`@bluefly/studio-ui`	ALL React UI components, shared UI components, reusable UI patterns	Creating React UI components in other projects

Decision Tree: Where to Build What

START: What are you building?
│
├─→ Service/Business Logic?
│   └─→ Which domain?
│       ├─→ Routing/Discovery → @bluefly/agent-router
│       ├─→ Agent Communication → @bluefly/agent-mesh
│       ├─→ Vector/Search/RAG → @bluefly/agent-brain
│       ├─→ Tracing/Observability → @bluefly/agent-tracer
│       ├─→ Docker/K8s → @bluefly/agent-docker
│       ├─→ Tailscale/Network → @bluefly/agent-tailscale
│       ├─→ Workflows/State → @bluefly/workflow-engine
│       ├─→ MCP/Protocol → @bluefly/agent-protocol
│       ├─→ LLM Providers → @bluefly/foundation-bridge
│       ├─→ Compliance/Audit → @bluefly/compliance-engine
│       └─→ Orchestration → @bluefly/agentic-flows
│
├─→ CLI Command or Script?
│   ├─→ Reusable/DRY code? → agent-buildkit (enhance existing commands)
│   ├─→ One-off script? → tmp/ directory (temporary)
│   └─→ agent-buildkit imports from `@bluefly/*` packages (never duplicate)
│
├─→ Agent registry / .agents/ validation / workspace discovery?
│   └─→ agent-buildkit (commands) + gitlab_components (CI templates)
│
├─→ IDE integration?
│   └─→ ide-supercharger (PULLS from agent-buildkit; does NOT duplicate)
│
├─→ Agent Definition (OSSA manifest)?
│   └─→ platform-agents/packages/@ossa/
│
├─→ React UI Component? → @bluefly/studio-ui
├─→ CI/CD Pipeline? → gitlab_components
├─→ API Schema? → api-schema-registry
├─→ Security Policy? → security-policies
├─→ Documentation? → technical-docs (GitLab Wiki)
├─→ Drupal Module/Theme/Recipe? → Individual git repos
└─→ Model Definition? → models/

Agent Role Separation

Agents must follow OSSA access tier definitions and role conflict rules. See architecture/separation-of-duties.md.

Access Tiers (OSSA v0.3.3)

Tier	Role	Can	Cannot
`tier_1_read`	Analyzer	Query APIs, scan code, reports	Create/modify resources, push, approve
`tier_2_write_limited`	Reviewer/Orchestrator	MR comments, create issues, coordinate	Push code, merge MRs, modify production
`tier_3_full_access`	Executor	Push code, create MRs, deploy to staging	Merge without review, deploy to prod, approve own
`tier_4_policy`	Approver	Approve MRs, authorize production	Push code, execute deployments, review own

Role Conflict Matrix

Role	Conflicts With	Reason
Analyzer	Executor, Approver	Cannot fix what you audit
Reviewer	Executor, Approver	Cannot approve own changes
Executor	Reviewer, Approver	Cannot review/approve own work
Orchestrator	Executor (direct)	Coordinator cannot directly execute
Approver	Executor, Reviewer	Cannot approve if involved in creation

Automated Enforcement

Pre-commit Hooks

npx @bluefly/compliance-engine check-imports --fail-on-violation
npx @bluefly/compliance-engine check-file-location --fail-on-violation
npx @bluefly/compliance-engine check-duplication --fail-on-violation

CI Pipeline Gate

All projects MUST include separation-of-duties-check component from gitlab_components.

Import Validation Rules

// Valid:
import { VectorSearchService } from '@bluefly/agent-brain';
import { QdrantClient } from '@bluefly/agent-brain/qdrant';

// VIOLATIONS:
import { internalHelper } from '@bluefly/agent-brain/src/internal/helpers';
import { something } from '../../agent-brain/src/services';