# Solveaux Architecture Protocol (.slvx) — Official Specification

> **Standard Version:** 1.1.0  
> **Status:** Living Standard / Active  
> **Published At:** https://solveaux.com/spec  
> **RFC Identifier:** RFC-SLVX-001  
> **Primary Extension:** `.slvx` (Fallback/Legacy: `.solveaux`, `.slx`)  
> **Badge Program:** Solveaux Certified Compatible Standard  
> **Target Audience:** Engineering Leads, Software Architects, AI Coding Assistants (Cursor, Claude Code, Copilot, Antigravity, Windsurf)

[![Solveaux .slvx Compatible](https://solveaux.com/badges/slvx-compatible.svg)](https://solveaux.com/spec)
[![Solveaux Certified Standard](https://solveaux.com/badges/slvx-certified.svg)](https://solveaux.com/spec)

---

## Table of Contents
1. [Executive Summary & Motivation](#1-executive-summary--motivation)
2. [File Placement & Repository Structure](#2-file-placement--repository-structure)
3. [Syntax & Grammar Specification](#3-syntax--grammar-specification)
4. [Entity Types](#4-entity-types)
   - [4.1 Architecture Decision Records ([DECISION] / [ADR])](#41-architecture-decision-records-decision-or-adr)
   - [4.2 Technical Research Spikes ([RESEARCH] / [SPIKE])](#42-technical-research-spikes-research-or-spike)
5. [Decision Lifecycle & Interactive Permission Governance](#5-decision-lifecycle--interactive-permission-governance)
6. [Configuring AI Coding Tools (Cursor, Claude Code, Copilot, Antigravity)](#6-configuring-ai-coding-tools)
7. [The "Certified Compatible" Badge Specification](#7-the-certified-compatible-badge-specification)
8. [Ingestion Workflows & Ecosystem](#8-ingestion-workflows--ecosystem)
9. [Reference Parser Implementation](#9-reference-parser-implementation)
10. [Specification Changelog](#10-specification-changelog)
11. [Dual-Licensing Architecture & Demarcation](#11-dual-licensing-architecture--demarcation)

---

## 1. Executive Summary & Motivation

The **`.slvx` Architecture Protocol** is an open, append-only, human-readable specification designed to capture architectural decisions, research spikes, and structural trade-offs directly inside code repositories.

### The Problem: "AI Amnesia" in Modern Engineering
With AI coding assistants (Cursor, Claude Code, GitHub Copilot, Antigravity), engineering velocity has increased 10x. However, the architectural reasoning, rejected alternatives, and security trade-offs remain trapped in ephemeral chat windows or developer heads.

Months later, teams suffer from **AI Amnesia**:
- Why was this ORM or state management pattern selected?
- What security trade-offs were accepted?
- Why did the team reject alternative libraries?

### Why Existing Formats Fail
| Format | Why It Fails for Architecture Decisions |
|---|---|
| **Plain JSON (`.json`)** | Prone to merge conflicts (a missing comma crashes `JSON.parse()`), unreadable for multi-line explanations, hostile to git diffs. |
| **YAML (`.yaml`)** | Highly sensitive to whitespace indentation; multi-line markdown inside YAML blocks causes frequent parsing breakage. |
| **Unstructured Markdown (`.md`)** | Great for humans, but lacks predictable AST schema for deterministic parsing, machine ingestion, and automated dependency graphs. |
| **The `.slvx` Standard** | Combines **pure Markdown readability** with **structured AST block predictability**. Append-only, zero merge conflicts, and costs **$0 in AI cloud token bills** to parse. |

---

## 2. File Placement & Repository Structure

Repositories implementing the `.slvx` standard must adhere to one of the following layouts:

### Pattern A: Modular Directory (Recommended for Active Teams)
For teams working across multiple feature branches, microservices, or monorepos:

```
my-repo/
├── .slvx/
│   ├── adr-001-auth-migration.slvx
│   ├── adr-002-postgres-indexing.slvx
│   └── spike-001-vector-db.slvx
├── src/
└── README.md
```

- **Naming format:** `.slvx/adr-<number>-<slug>.slvx` or `.slvx/spike-<number>-<slug>.slvx`
- **Benefits:** Clean Git PR reviews, zero chance of merge collisions, isolated tracking per feature branch.

### Pattern B: Single Root File (Default for Simple Projects)
For smaller libraries or compact codebases:

```
my-repo/
├── project.slvx       # Authoritative protocol file
├── src/
└── README.md
```

Fallback path accepted: `.slvx/project.slvx`.

> **File Extension:** Strictly `.slvx`. Parsers MAY accept `.solveaux` or `.slx` as backward-compatible legacy aliases.

---

## 3. Syntax & Grammar Specification

A `.slvx` file consists of an optional file header followed by one or more **Entity Blocks** separated by standard markdown horizontal rules (`---`).

### 3.1 File Header (Optional)
The top of a `.slvx` file may declare file-level metadata:

```solveaux
# ==============================================================================
# Solveaux Architecture Protocol (.slvx v1.1)
# Project: <project-name> | Org: <organization-name>
# Version: 1.1.0
# ==============================================================================
```

### 3.2 Block Structure
Each entity block is bounded by `---` and structured into two layers:
1. **Header Layer:** Block identifier tag and key-value metadata attributes.
2. **Body Layer:** Standard Markdown headings (`##`) containing narrative explanations.

```solveaux
---
[ENTITY_TAG] IDENTIFIER: <Title>
Key: <Value>
Key: <Value>

## Section 1
<Markdown content>

## Section 2
<Markdown content>
---
```

### 3.3 Formal Grammar (EBNF)
```ebnf
slvx_file      ::= [ header_comment ] { entity_block } ;
entity_block   ::= "---" LF tag_line LF { metadata_line LF } blank_line { section_block } [ "---" ] ;
tag_line       ::= "[" ( "DECISION" | "ADR" | "RESEARCH" | "SPIKE" ) "]" [ identifier ":" ] title ;
metadata_line  ::= key ":" value ;
key            ::= "Status" | "Author" | "Date" | "Files" | "Model" | "Category" ;
section_block  ::= "## " section_title LF narrative_body ;
```

---

## 4. Entity Types

### 4.1 Architecture Decision Records (`[DECISION]` or `[ADR]`)
Captures structural, design, infrastructure, or library choices.

* **Block Tag:** `[DECISION]` or `[ADR]`
* **Metadata Fields:**
  * `Status:` *(Required)* `Proposed` | `Accepted` | `Deprecated`
  * `Author:` *(Optional)* Name or handle (e.g. `Sarah Chen (via Cursor)`)
  * `Date:` *(Optional)* ISO format (`YYYY-MM-DD`)
  * `Files:` *(Optional)* Comma-separated list of affected file paths relative to repo root
  * `Model:` *(Optional)* AI model or tool used (e.g. `Claude 3.7 Sonnet`, `GPT-4o`, `Cursor`)
* **Standard Body Sections:**
  * `## Context` (or `## Problem`, `## Background`): What problem triggered this decision?
  * `## Options Considered` (or `## Alternatives`): Trade-offs of rejected solutions.
  * `## Decision & Trade-offs` (or `## Decision Made`): What was decided and why.
  * `## Consequences` (or `## Impact`): Expected impact on performance, maintainability, or tech debt.

#### Decision Example
```solveaux
---
[DECISION] ADR-042: Migrate Client-Side Caching to TanStack React Query v5
Status: Accepted
Author: Sarah Chen (via Claude Code)
Date: 2026-09-27
Files: src/lib/queryClient.ts, src/app/providers.tsx, src/hooks/useDecisions.ts
Model: Claude 3.7 Sonnet

## Context
Multiple components across dashboard routes were independently fetching the same Supabase tables, causing redundant HTTP roundtrips and inconsistent local cache states during optimistic updates.

## Options Considered
1. SWR (Vercel) — Lightweight, but less robust mutation and cache invalidation primitives for complex relational graphs.
2. TanStack React Query v5 — Best-in-class garbage collection, structural sharing, and devtools integration.
3. Custom Zustand cache slice — Required custom retry logic and manual serialization.

## Decision & Trade-offs
Adopted TanStack React Query v5 with a global staleTime of 60 seconds and window focus refetching disabled on mobile.
Trade-off: Added 12kB to the initial client bundle.

## Consequences
- Deduplicated all concurrent Supabase API calls.
- Automated cache invalidation on decision updates.
- Standardized data loading patterns for team onboarding.
---
```

### 4.2 Technical Research Spikes (`[RESEARCH]` or `[SPIKE]`)
Documents technical evaluations, benchmarks, and prototype experiments.

* **Block Tag:** `[RESEARCH]` or `[SPIKE]`
* **Metadata Fields:**
  * `Category:` *(Optional, default: General)* e.g. `Database`, `Frontend`, `Security`, `AI/LLM`
  * `Author:` *(Optional)* Name or handle
  * `Date:` *(Optional)* ISO format (`YYYY-MM-DD`)
  * `Files:` *(Optional)* Associated code files
* **Standard Body Sections:**
  * `## Key Insights` (or `## Takeaways`): High-level conclusions.
  * `## Content` (or `## Findings`, `## Benchmarks`): Detailed test results and evidence.

---

## 5. Decision Lifecycle & Interactive Permission Governance

The `.slvx` specification enforces clear governance between autonomous AI coding agents and human tech leads:

```
       +---------------------------------------------+
       | AI Agent / Contributor                      |
       | Drafts change & requests chat approval      |
       +---------------------------------------------+
                              |
                              v
             [Status: Proposed]  <-- Logged in .slvx
                              |
                              v
                +---------------------------+
                | Human Tech Lead Review    |
                | (GitHub PR / Solveaux UI) |
                +---------------------------+
                     /                 \
                    /                   \
                   v                     v
          [Status: Accepted]     [Status: Deprecated]
             (Active Law)            (Superseded)
```

1. **Status: Proposed:** AI coding assistants or junior developers MUST commit records with `Status: Proposed` unless explicit architect permission has been granted.
2. **Status: Accepted:** The architecture choice is officially endorsed and accepted by tech leadership. AI agents treat Accepted records as authoritative codebase constraints.
3. **Status: Deprecated:** The decision has been superseded or retired. AI agents are forbidden from using patterns from deprecated records.

---

## 6. Configuring AI Coding Tools

To have AI assistants automatically generate valid `.slvx` records without human cognitive overhead, add these rule templates to your repository:

### 6.1 For Cursor: Add to `.cursorrules`
```markdown
### Solveaux Architecture Protocol (.slvx)
Whenever you make a non-trivial architectural choice, add a new library dependency, or resolve a technical trade-off:
Silently append a [DECISION] block to `project.slvx` (or create a new file under `.slvx/adr-XXX-<slug>.slvx`) in this format:

---
[DECISION] ADR-XXX: <Clear Actionable Title>
Status: Proposed
Author: User (via Cursor)
Date: <YYYY-MM-DD>
Files: <comma-separated files modified>

## Context
<Problem and motivation>

## Options Considered
1. <Alternative A> (Trade-offs)
2. <Alternative B> (Selected)

## Decision & Trade-offs
<The final decision made and why>

## Consequences
<Performance, maintainability, or architectural impact>
---
```

### 6.2 For Claude Code: Add to `CLAUDE.md`
```markdown
## Solveaux Architecture Protocol (.slvx)
When implementing significant architectural decisions or dependencies:
1. Check existing `.slvx` files to respect established codebase patterns.
2. Record changes in `project.slvx` or `.slvx/adr-XXX.slvx` using the official `.slvx` block format.
```

### 6.3 For Antigravity / Gemini: Add to `AGENTS.md`
```markdown
## Solveaux Architecture Governance (.slvx)
Before introducing new libraries or changing core design patterns:
- Propose the decision to the developer.
- On approval, append a [DECISION] block with Status: Accepted to `project.slvx`.
```

---

## 7. The "Certified Compatible" Badge Specification

Repositories, tools, and libraries complying with the `.slvx` specification are eligible to display the **Solveaux Certified Compatible** badge.

### 7.1 Badge Embed Codes

#### Standard Compatible Badge (Markdown)
```markdown
[![Solveaux .slvx Compatible](https://solveaux.com/badges/slvx-compatible.svg)](https://solveaux.com/spec)
```

#### Certified Standard Badge (Markdown)
```markdown
[![Solveaux Certified Standard](https://solveaux.com/badges/slvx-certified.svg)](https://solveaux.com/spec)
```

#### Compact Architecture Shield (Markdown)
```markdown
[![Architecture: .slvx](https://solveaux.com/badges/slvx-shield.svg)](https://solveaux.com/spec)
```

#### HTML Embed
```html
<a href="https://solveaux.com/spec" target="_blank" rel="noopener noreferrer">
  <img src="https://solveaux.com/badges/slvx-compatible.svg" alt="Solveaux .slvx Compatible" height="20" />
</a>
```

### 7.2 Certification Compliance Levels
- **Level 1 — Format Compliant:** Repository contains valid `.slvx` files conforming to the EBNF grammar in Section 3.
- **Level 2 — Continuous Ingestion:** Repository automatically syncs `.slvx` records via GitHub Actions or Git pre-push hooks.
- **Level 3 — MCP Real-Time Sync:** Development environment connects to the Solveaux MCP server, feeding active ADRs into AI agent context.

---

## 8. Ingestion Workflows & Ecosystem

The `.slvx` standard is designed to be completely open. Repositories own their `.slvx` files; Solveaux provides the automated visualization and intelligence ecosystem.

### Method A: Web UI Drag & Drop (Zero Setup)
1. Open your project on Solveaux: `/organizations/[id]/projects/[projectId]/decisions`.
2. Click **Sync .slvx** in the navigation bar.
3. Drag-and-drop your `.slvx` file(s).
4. Review instant parsed visual diffs and commit to the centralized knowledge hub.

### Method B: Automated CI/CD GitHub Action
```yaml
# .github/workflows/solveaux-sync.yml
name: Sync Architecture Decisions (.slvx)

on:
  push:
    branches: [main]
    paths:
      - 'project.slvx'
      - '.slvx/**'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Push .slvx to Solveaux
        run: |
          curl -X POST "https://solveaux.com/api/organizations/${{ secrets.SOLVEAUX_ORG_ID }}/projects/${{ secrets.SOLVEAUX_PROJECT_ID }}/sync" \
            -H "x-api-key: ${{ secrets.SOLVEAUX_PROJECT_KEY }}" \
            -H "Content-Type: text/plain" \
            --data-binary "@project.slvx"
```

### Method C: Solveaux MCP Server
Run the local MCP daemon to allow Cursor, Claude Desktop, and Antigravity to query and create `.slvx` records in real time:
```bash
npx solveaux-mcp --key=slvx_proj_YOUR_SECRET_KEY
```

---

## 9. Reference Parser Implementation

Solveaux uses an open, zero-cost, deterministic TypeScript regex state machine to parse `.slvx` files without external AI tokens.

```typescript
export function parseSlvxBlock(content: string) {
  const blocks = content.replace(/\r\n/g, "\n").split(/\n---\s*\n/);
  return blocks.map(block => {
    const isDecision = /\[(?:DECISION|ADR)\]\s*(.+)/i.test(block);
    const isResearch = /\[(?:RESEARCH|SPIKE)\]\s*(.+)/i.test(block);
    return { block, isDecision, isResearch };
  });
}
```

---

## 10. Specification Changelog

### v1.1.0 — 2026-09-27 (Current Standard)
- **Standardized Extension:** Formalized `.slvx` as the official, canonical file extension across all tools, replacing legacy references to `.solveaux`.
- **Modular Directory Hierarchy:** Added official support for `.slvx/adr-*.slvx` files alongside single `project.slvx` root files.
- **Interactive Permission Governance:** Added strict distinction between `Proposed` and `Accepted` states for autonomous AI coding agents.
- **Certified Compatible Badge Program:** Launched the official badge specification, SVG assets, and compliance tiers.
- **MCP Real-Time Schema:** Standardized tool definitions for the Model Context Protocol bridge.

### v1.0.0 — 2026-08-15
- **Initial Release:** First public release of the Solveaux Architecture Protocol.
- **Core Grammar:** Introduced block delimiters (`---`), `[DECISION]` and `[RESEARCH]` tags, and standard markdown narrative sections.
- **Zero-Token Engine:** Released the deterministic client-side parser.

---

## 11. Dual-Licensing Architecture & Demarcation

The Solveaux ecosystem operates on a clear **Open Specification / Commercial Engine** dual-licensing framework:

| Dimension | 🌐 Open Specification (`.slvx`) | 🔒 Proprietary Solveaux Cloud Platform |
| :--- | :--- | :--- |
| **Asset Class** | Architectural File Format & Protocol Standard | Multi-Tenant Cloud SaaS & Enterprise Dashboard |
| **Governing License** | **Open Community Standard** (CC BY 4.0 / Apache 2.0 Reference) | **Proprietary Commercial License** (All Rights Reserved) |
| **Components Covered** | • `.slvx` grammar, delimiters (`---`), and syntax<br>• `[DECISION]` and `[RESEARCH]` tags<br>• Local `.slvx/` directory conventions<br>• Zero-cost deterministic regex parser algorithm<br>• "Governed by Solveaux" badge SVG specifications | • Multi-tenant synchronization gateway (`/api/.../sync`)<br>• Solveaux MCP Server & Agent RBAC engine (`/api/mcp`)<br>• Interactive system architecture knowledge graph canvas<br>• Continuous validation pipelines & conflict analysis<br>• Multi-project team workspaces, soft-delete, and audit logs |
| **Usage Freedom** | **100% Free & Royalty-Free:** Any IDE, agent, or commercial tool can produce or consume `.slvx` files without fees or lock-in. | **Subscription-Based:** Available via Early Access program transitioning into commercial subscription tiers. |
| **User Data Sovereignty** | **100% Customer Property:** The `.slvx` files committed to git belong entirely to your organization. | **Customer Governed:** Solveaux never trains public AI models on your private architectural intelligence. |
| **Anti-Cloning Protections** | Permitted to build independent `.slvx` parsers, linters, and formatters. | Strictly prohibited to reverse engineer, decompile, clone, scrape, or white-label the Solveaux SaaS platform. |

For detailed legal terms and trademark usage policies, review [DUAL_LICENSING.md](DUAL_LICENSING.md) and [Solveaux Brand Guidelines](https://solveaux.com/brand).