How to Use and Customize the Technical Preferences System in AIOX

The technical preferences system in AIOX is a markdown-based configuration layer stored in .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 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 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 at lines 447–463 in packages/installer/src/wizard/index.js. To change later, edit the YAML file manually:

# .aiox-core/core-config.yaml

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

Modifying User-Level Preferences

Open .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.

### 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. Create a folder my-preset/ with a 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:

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

The wizard updates both technical-preferences.md (adding a comment indicating the chosen preset) and core-config.yaml at lines 410–418 in 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:

// ./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 programmatically to switch stacks:

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:

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, 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, writable manually or through the installer wizard at 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 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 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 describing your stack, then reference it in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}