# How to Use and Customize the Technical Preferences System in AIOX

> Master the AIOX technical preferences system. Learn how to customize this markdown-based configuration layer for consistent agent behavior and project technology stacks. Ensure seamless team collaboration.

- Repository: [SynkraAI/aiox-core](https://github.com/synkraai/aiox-core)
- Tags: how-to-guide
- Published: 2026-03-15

---

**The technical preferences system in AIOX is a markdown-based configuration layer stored in [`.aiox-core/data/technical-preferences.md`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/data/technical-preferences.md) that defines your project's technology stack and coding conventions, which the `AgentConfigLoader` automatically injects into every agent to ensure consistent, context-aware behavior across your development team.**

The technical preferences system in AIOX serves as the central source of truth for project-wide technology choices, allowing teams to standardize their stack across all AI agents. Located in the SynkraAI/aiox-core repository, this system combines preset stack definitions with customizable user preferences to guide code generation and architectural decisions according to your specific requirements.

## What Is the Technical Preferences System?

AIOX stores a **technical-preferences** layer that lets a project define its preferred technology stack, coding-style conventions, and other team-wide defaults. The layer lives in the file **[`.aiox-core/data/technical-preferences.md`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/data/technical-preferences.md)** and is automatically loaded by the **`AgentConfigLoader`** for every agent (dev, qa, architect, etc.)—see the trace in the QA-agent execution test.

The file contains two main sections:

- **Tech Preset**: A named preset (e.g., `nextjs-react`, `go`, `rust`) that bundles a complete stack definition. The active preset is referenced from **[`.aiox-core/core-config.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/core-config.yaml)** under `techPreset.active`.
- **User Preferences**: Free-form tables or bullet lists where a team can record preferred frameworks, styling libraries, state-management tools, database, ORM, and coding-style rules. These entries are read by agents when they generate code or documentation.

## How the Configuration Loader Works

When AIOX starts, `AgentConfigLoader.loadFile()` reads the markdown file (approximately 15 KB) and makes the data available via `AgentConfigLoader.getTechnicalPreferences()`. All agents that need stack-aware decisions (e.g., `@dev` scaffolding a component, `@architect` recommending patterns) query that API, guaranteeing consistent behaviour across the whole squad as implemented in SynkraAI/aiox-core.

## Customizing the Technical Preferences System

### Switching Tech Presets via Configuration

During project-initialisation, the installer wizard asks "Which preset would you like to use?" and writes the chosen preset name into [`core-config.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/core-config.yaml) at lines 447–463 in [`packages/installer/src/wizard/index.js`](https://github.com/SynkraAI/aiox-core/blob/main/packages/installer/src/wizard/index.js). To change later, edit the YAML file manually:

```yaml

# .aiox-core/core-config.yaml

techPreset:
  active: go            # ← switch to the Go preset

```

### Modifying User-Level Preferences

Open [`.aiox-core/data/technical-preferences.md`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/data/technical-preferences.md) and edit the markdown tables or bullet sections. Uncomment the example rows or add new ones; the file is plain text, no JSON/YAML required. Agents read these entries at lines 58–71 when generating code or documentation.

```markdown

### Preferred Technologies

| Category           | Preference    | Notes                     |
|--------------------|---------------|---------------------------|
| Frontend Framework | React         | Using App Router          |
| Styling            | Tailwind CSS  | With shadcn/ui            |
| State Management   | Zustand       | Global UI state           |
| Database           | PostgreSQL    | Supabase-hosted           |
| ORM                | Prisma        | Type-safe queries         |

```

Persist the changes through version control so every teammate (and every CI run) gets the same defaults.

### Creating Custom Presets

Presets are simple markdown files placed in **`.aiox-core/data/tech-presets/`** and referenced by name in [`core-config.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/core-config.yaml). Create a folder `my-preset/` with a [`README.md`](https://github.com/SynkraAI/aiox-core/blob/main/README.md) describing the stack, then set `active: my-preset` according to the file structure documented at lines 5–13 of the technical preferences file.

### Using the Interactive Wizard

Re-run the installer to switch presets interactively:

```bash
npx aiox-core install   # re-run installer, choose a new preset

```

The wizard updates both [`technical-preferences.md`](https://github.com/SynkraAI/aiox-core/blob/main/technical-preferences.md) (adding a comment indicating the chosen preset) and [`core-config.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/core-config.yaml) at lines 410–418 in [`packages/installer/src/wizard/index.js`](https://github.com/SynkraAI/aiox-core/blob/main/packages/installer/src/wizard/index.js).

## Programmatic Access Examples

### Load Technical Preferences via Node.js

Access the same file agents use internally to inspect current settings:

```javascript
// ./scripts/load-tech-prefs.js
import fs from 'fs';
import path from 'path';
import matter from 'gray-matter'; // parses front-matter if present

const TECH_PREFS_PATH = path.resolve('.aiox-core/data/technical-preferences.md');

export function getTechnicalPreferences() {
  const raw = fs.readFileSync(TECH_PREFS_PATH, 'utf8');
  // The file is plain markdown; you can parse sections with a simple regex
  const presetMatch = raw.match(/techPreset:\s*\n\s*active:\s*(\S+)/);
  const activePreset = presetMatch?.[1] ?? null;

  // Extract the "Preferred Technologies" table (optional)
  const tableMatch = raw.match(/### Preferred Technologies([\s\S]*?)###/);

  const techTable = tableMatch?.[1]?.trim() ?? '';

  return { activePreset, techTable };
}

// Example usage
console.log(getTechnicalPreferences());

```

### Change the Active Preset from a Script

Modify [`core-config.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/core-config.yaml) programmatically to switch stacks:

```javascript
import yaml from 'js-yaml';
import fs from 'fs';
import path from 'path';

const CORE_CFG_PATH = path.resolve('.aiox-core/core-config.yaml');

export function setActivePreset(presetName) {
  const cfg = yaml.load(fs.readFileSync(CORE_CFG_PATH, 'utf8'));
  cfg.techPreset = cfg.techPreset || {};
  cfg.techPreset.active = presetName;
  fs.writeFileSync(CORE_CFG_PATH, yaml.dump(cfg), 'utf8');
  console.log(`✅ Active tech preset set to "${presetName}"`);
}

// Usage
setActivePreset('go');

```

### CLI Snippet to View Current Preferences

Quickly check your configuration without opening files:

```bash
node -e "import('./scripts/load-tech-prefs.js').then(m=>console.log(m.getTechnicalPreferences()))"

```

## Summary

- The technical preferences system in AIOX resides in [`.aiox-core/data/technical-preferences.md`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/data/technical-preferences.md), a markdown file parsed by `AgentConfigLoader` for all agents.
- **Tech Presets** (defined in `.aiox-core/data/tech-presets/`) provide bundled stack definitions, while **User Preferences** allow custom tables for frameworks, databases, and style rules.
- The active preset is controlled via `techPreset.active` in [`.aiox-core/core-config.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/core-config.yaml), writable manually or through the installer wizard at [`packages/installer/src/wizard/index.js`](https://github.com/SynkraAI/aiox-core/blob/main/packages/installer/src/wizard/index.js).
- All changes are version-controllable plaintext, ensuring consistent agent behavior across local development and CI pipelines.

## Frequently Asked Questions

### Where is the technical preferences file located?

The primary file is [`.aiox-core/data/technical-preferences.md`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/data/technical-preferences.md) in your project root. This markdown file serves as the central store for both preset references and user-defined technology preferences, automatically loaded by the `AgentConfigLoader` class whenever AIOX initializes an agent session.

### How do I change the active technology preset?

Edit [`.aiox-core/core-config.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/core-config.yaml) to update the `techPreset.active` field with your desired preset name (e.g., `nextjs-react`, `go`, or `rust`). Alternatively, run `npx aiox-core install` to launch the interactive wizard, which updates both the YAML configuration and adds a reference comment to the technical preferences markdown file.

### Can I create custom presets for my organization?

Yes. Create a new directory inside `.aiox-core/data/tech-presets/` with your preset name (e.g., `my-preset/`), add a [`README.md`](https://github.com/SynkraAI/aiox-core/blob/main/README.md) describing your stack, then reference it in [`core-config.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/core-config.yaml) as `active: my-preset`. This allows teams to distribute standardized internal stacks across multiple repositories while maintaining the same agent behavior.

### How do agents access these preferences during execution?

Agents call `AgentConfigLoader.getTechnicalPreferences()` after the loader reads the markdown file via `loadFile()`. This API provides the active preset and user preference tables, enabling agents like `@dev` and `@architect` to generate code that respects your specified frameworks, ORMs, and styling conventions without hardcoding assumptions.