FlossWare Engineering Standards

This repository defines shared engineering standards, architecture decisions, and development conventions for the FlossWare ecosystem.

Core Principles

Configuration is the source of truth.
Defaults are minimal; capabilities are explicitly enabled.
Components are modular and composable.
Prefer open standards and free-first implementations.
Avoid unnecessary coupling.
Favor automation, repeatability, and infrastructure-as-code.
Agent-neutral: capabilities and infrastructure, not a required agent runtime or UI.
Capability before protocol; security at capability boundaries.

See ADR-0009 and ADR-0016 for normative statements.

Architecture decisions are documented as ADRs under adr/.

ADR	Topic
ADR-0001	Explicit Opt-In Cross-Cutting Behavior
ADR-0002	AI Provider Abstraction
ADR-0003	No Local Inference by Default
ADR-0004	MCP and Tool Contracts
ADR-0005	Event-Driven Internal Bus
ADR-0006	Cross-Cutting Decorators
ADR-0007	Unified Client-Service Contract
ADR-0008	Free-First Modular Platform
ADR-0009	Core Architecture Principles
ADR-0010	REST Service Boundaries and Integration
ADR-0011	Stored Procedure Database Access Policy
ADR-0012	Multi-Model Consensus for Quality Gates
ADR-0013	Bandit-Based Model Selection
ADR-0014	Token Budget Management
ADR-0015	Dynamic AI Model Inventory
ADR-0016	Configuration as Source of Truth
ADR-0017	Agent-Neutral Architecture
ADR-0018	MCP Capability Exposure
ADR-0019	Agent Tool Security and Authorization
ADR-0020	Capability and Protocol Separation

New ADRs SHOULD use adr/TEMPLATE.md.

All ADRs should include:

RFC 2119 keywords are used consistently:

SHALL / SHALL NOT: mandatory requirements (MUST is treated as equivalent to SHALL)
SHOULD / SHOULD NOT: recommended practices
MAY: optional behavior