How to Configure technical-preferences.md for Personalized Agent Behavior in aios-core

To configure personalized agent behavior in aios-core, edit .aios-core/data/technical-preferences.md to define your tech stack, coding style rules, and project-specific constraints, then commit the changes so AgentConfigLoader automatically injects these preferences into every agent activation.

The technical-preferences.md file serves as the central technical profile for the aios-core ecosystem, ensuring that every AI agent—whether @dev, @architect, or @qa—operates according to your team's specific standards. Located at .aios-core/data/technical-preferences.md, this markdown file is automatically loaded during agent activation and injected into the LLM prompt context, making it the single source of truth for how to configure technical-preferences.md for personalized agent behavior in aios-core.

What Is technical-preferences.md and Why It Matters

technical-preferences.md is a plain Markdown file that acts as a living knowledge base for your project's technical DNA. According to the aios-core source code, the file serves four critical functions:

• Consistency: All agents consult the same preferences, guaranteeing uniform recommendations across the codebase.
• Efficiency: Eliminates the need to repeat stack or style specifications in every prompt.
• Personalization: Encodes your "house rules," such as preferred frameworks, naming conventions, and architectural patterns.
• Learning: Evolves with each project, becoming a centralized record of technical decisions.

Because the file uses HTML comments for placeholders, you can keep extensive notes and examples without affecting how AgentConfigLoader parses the content.

How the AgentConfigLoader Reads Your Preferences

When an agent starts, the AgentConfigLoader executes a specific sequence to make your technical preferences available. As traced in docs/guides/agents/traces/architect-execution-trace.md, the loader performs these steps:

1. Load core config → reads .aios-core/data/agent-config-requirements.yaml.
2. Determine required files → identifies technical-preferences.md under devLoadAlwaysFiles and similar sections for other agent types, as shown in docs/guides/agents/traces/dev-execution-trace.md.
3. Load the file → executes AgentConfigLoader.loadFile('.aios-core/data/technical-preferences.md') (approximately 15 KB in size).
4. Inject into context → makes the content available via the template system (aios-core/utils/template-format.md) using the {{technicalPreferences}} syntax.

The installer wizard at packages/installer/src/wizard/index.js (lines 408-415) can also auto-populate this file when you select a preset during initial project setup.

Step-by-Step Guide to Configuring technical-preferences.md

1. Select a Tech Preset (Optional)

The file ships with a Tech Presets table listing ready-made stacks (e.g., nextjs-react). You can activate a preset by modifying .aios-core/core-config.yaml without editing the markdown file directly:

# .aios-core/core-config.yaml

techPreset:
  active: nextjs-react   # ← change to your preset name

The @dev agent automatically loads the active preset during activation.

2. Define Your Preferred Technologies

Uncomment the HTML-comment block under Preferred Technologies and populate the table with your stack choices:

| Category          | Preference   | Notes                         |
|-------------------|--------------|------------------------------|
| Frontend Framework| React        | Prefer hooks over classes    |
| Styling           | Tailwind CSS | Use shadcn/ui components    |
| State Management  | Zustand      | Simple global store          |
| Database          | PostgreSQL   | Managed via Supabase         |
| ORM               | Prisma       | Type‑safe queries            |

3. Set Coding Style Rules

Uncomment the Coding Style Preferences section and add your team's style guide rules:

- Prefer functional components over class components
- Use named exports instead of default exports
- Enforce explicit error handling (no generic `catch {}` blocks)

4. Add Project-Specific Constraints

Use the Project-Specific Rules section for architectural constraints that agents must respect:

- Disallow direct DB queries from frontend code
- Require ESLint `@typescript-eslint/no-explicit-any`
- All new services must include unit tests with > 80 % coverage

5. Commit and Activate

Save your changes and commit them to version control:

git add .aios-core/data/technical-preferences.md
git commit -m "Update technical preferences: switch to nextjs‑react preset and add team coding style"

The AgentConfigLoader automatically picks up these changes on the next agent activation—no restart required.

Complete Configuration Example

Here is a minimal yet complete example that demonstrates how to configure technical-preferences.md for personalized agent behavior in aios-core:

# User-Defined Preferred Patterns and Preferences

## Tech Presets

| Preset         | Technologies                                                   | Best For                         |
| -------------- | -------------------------------------------------------------- | -------------------------------- |
| `nextjs-react` | Next.js 14+, React, TypeScript, Tailwind, Zustand, React Query | Full‑stack web apps, SaaS        |

## Active Preset

> **Current:** `nextjs-react`

## User Preferences

### Preferred Technologies

| Category          | Preference   | Notes                         |
|-------------------|--------------|------------------------------|
| Frontend Framework| React        | Hooks only                    |
| Styling           | Tailwind CSS | Use shadcn/ui                |
| State Management  | Zustand      | Global store only             |
| Database          | PostgreSQL   | Supabase integration          |
| ORM               | Prisma       | Strict type safety            |

### Coding Style Preferences

- Prefer functional components over class components
- Use named exports instead of default exports
- Enforce explicit error handling (no generic catches)

### Project‑Specific Rules

- Disallow direct DB queries from the UI layer
- All new services must include unit tests with > 80 % coverage

After committing this file, any subsequent @dev, @architect, or @qa interaction will automatically respect these choices.

Key Integration Points and File References

Understanding the ecosystem helps you leverage technical-preferences.md effectively:

File	Role	Location
.aios-core/data/technical-preferences.md	Central technical profile (editable)	/.aios-core/data/technical-preferences.md
.aios-core/core-config.yaml	Core configuration for active presets	/.aios-core/core-config.yaml
.aios-core/data/agent-config-requirements.yaml	Defines which files agents must load	/.aios-core/data/agent-config-requirements.yaml
packages/installer/src/wizard/index.js	Auto-updates preferences when selecting presets (lines 408-415)	/packages/installer/src/wizard/index.js
aios-core/utils/template-format.md	Template syntax documentation for embedding preferences	/aios-core/utils/template-format.md
docs/guides/agents/traces/architect-execution-trace.md	Activation trace showing loader behavior	/docs/guides/agents/traces/architect-execution-trace.md

Summary

• Location: Edit .aios-core/data/technical-preferences.md to define your team's technical DNA.
• Loading: AgentConfigLoader automatically injects this file into every agent activation context via devLoadAlwaysFiles configuration.
• Presets: Switch tech stacks by setting techPreset.active in .aios-core/core-config.yaml without rewriting the markdown.
• Customization: Uncomment HTML-commented sections to specify preferred technologies, coding styles, and project-specific constraints.
• Activation: Commit changes to git; agents pick up updates immediately on next task execution.

Frequently Asked Questions

Where is technical-preferences.md located in aios-core?

The file is located at .aios-core/data/technical-preferences.md relative to your project root. This path is hard-coded into the AgentConfigLoader class, which references it under devLoadAlwaysFiles in the agent configuration requirements.

How do I switch between tech presets without editing the markdown file?

Modify the .aios-core/core-config.yaml file and update the techPreset.active field to your desired preset name (e.g., nextjs-react). The @dev agent reads this configuration during activation and automatically applies the corresponding technology stack defined in the presets table of technical-preferences.md.

Do I need to restart agents after updating technical-preferences.md?

No. The AgentConfigLoader reads .aios-core/data/technical-preferences.md fresh during each agent activation cycle. Once you commit your changes to version control, the next task executed by any @dev, @architect, or @qa agent will immediately incorporate your updated preferences into its context.

Can I use HTML comments to keep placeholder notes in the file?

Yes. The parser specifically supports HTML-style comments (e.g., <!-- Note: consider Vue for future projects -->) so you can keep placeholder text, reminders, or alternative configurations without affecting the agent's interpretation of your active preferences. This allows the file to serve as both a live configuration and a documented knowledge base.

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