This repository defines shared engineering standards, architecture decisions, and development conventions for the FlossWare ecosystem.
- Configuration is the source of truth.
- Defaults are minimal; capabilities are explicitly enabled.
- Components are modular and composable.
- Provider- and pricing-neutral: no AI provider, model vendor, hosting topology, or pricing tier is an architectural default.
- 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.
- Released artifacts are derived, reproducible delivery outputs, not sources of truth.
See ADR-0009, ADR-0016, ADR-0021, ADR-0022, and ADR-0023 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 | Historical Free-First Platform Policy (Superseded) |
| 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 |
| ADR-0021 | Provider-Neutral AI Selection |
| ADR-0022 | Reproducible Build Artifacts and Distribution |
| ADR-0023 | Canonical FlossWare AI Persistent State Root |
New ADRs SHOULD use adr/TEMPLATE.md.
- ADR-0020 — capability vs protocol
- ADR-0004 — MCP preference for agents
- ADR-0018 — MCP exposure rules
- ADR-0019 — tool security
- ADR-0017 — agent-neutral posture
- ADR-0021 — provider and pricing neutrality
- ADR-0022 — reproducible artifact distribution
- ADR-0023 — persistent AI state ownership
All ADRs should include:
- Status
- Date
- Context
- Scope and Non-goals (recommended; required for new ADRs)
- Decision
- Consequences (positive and negative)
- Alternatives considered
- Related ADRs
RFC 2119 keywords are used consistently:
- SHALL / SHALL NOT: mandatory requirements (MUST is treated as equivalent to SHALL)
- SHOULD / SHOULD NOT: strong recommendation
- MAY: optional behavior