DEV Community: Hamed Hajiloo

Centralized Rule Structures

Hamed Hajiloo — Thu, 30 Jul 2026 08:38:53 +0000

Enforcing AI Agent Adherence Through Single-Source Architecture in CrystaCode projects

AI agents require strict directory structures to execute project rules without logic divergence. Rule duplication causes execution failure. Establish a single source of truth. Define each rule in exactly one location. Secondary files function exclusively as routing parameters.

System Architecture

AGENTS.md                        # Primary entry file
CLAUDE.md                        # Pointer to AGENTS.md

agents/
  rules/
    productA.md                  # Component directives
    productB.md
  skills/
    styling-guidelines-a/SKILL.md
    styling-guidelines-b/SKILL.md
  hooks/
    styling-guard.ps1            # Interceptor execution script

docs/
  Conventions/
    ProductA/styling-guidelines.md   # Absolute rule text
    ProductB/styling-guidelines.md

.claude/
  settings.json                  # Claude hook directive
  skills/*/SKILL.md              # Auto-generated artifacts

.github/
  instructions/*.instructions.md # GitHub agent pointers
  hooks/preToolUse.json          # GitHub hook directive

Component Specifications

Primary Node

AGENTS.md: The mandatory initialization file. Contains routing matrices. Outlines file extension triggers and maps them to specific requisite documents.

Redirection Nodes

CLAUDE.md: Contains a single pointer instructing the parser to evaluate AGENTS.md.
.github/instructions/: Pointers redirecting GitHub Copilot to module-specific rules.

Operational Directives

agents/rules/: Isolated procedural steps and checklists mapped to specific project modules. Defers rule definitions to the skills directory.
agents/skills/: Contextual triggers dictating exact pre-conditions for operation. Defers absolute rule text to the docs/ repository.

Absolute Documentation

docs/: The definitive repository. Contains complete technical specifications and rule text. The sole location for rule definitions.

Automated Mirrors

.claude/skills/: Automated mirror of agents/skills. Manual modification is strictly prohibited.

Interceptor Script Protocol

The styling-guard.ps1 hook enforces compliance by gating execution based on session markers.

Intercept Request:
The script intercepts the AI file modification request pre-execution.
Evaluate Target Parameters:
The file extension is evaluated against target parameters (.scss, .razor). Unmatched files bypass interception.
Ascertain Product Association:
The script evaluates the target file path to identify the associated project module.
Query Session Data:
The script checks session data for an existing execution marker corresponding to the file type and module. If present, the AI bypasses interception.
Halt Execution:
If the marker is absent, execution is blocked. The AI receives an explicit directive to parse the required skill documentation.
Write Execution Marker:
The script writes the execution marker to session data. Subsequent modification attempts in the same session proceed without interruption.

Interceptor Implementation Logic
The interception mechanism outputs explicit standard error directives to halt execution when session markers are absent:

Deployment Checklist

if ($category -eq 'scss') {
    [Console]::Error.WriteLine(
        "MANDATORY styling gate: this is the first .scss edit in this session for the " +
        "'$product' product. Invoke the '$skill' skill (canonical rules: $doc), apply its " +
        "rules -- $checklist -- then retry this exact edit. $forbidden " +
        "This gate fires once per session per product per file category.")
} else {
    [Console]::Error.WriteLine(
        "MANDATORY component gate: this is the first .razor edit in this session for the " +
        "'$product' product. Before this edit: (1) invoke the '$skill' skill (canonical " +
        "rules: $doc) for color/typography/component conventions -- use $components. " +
        "(2) invoke the 'localize-app-strings' skill -- never hardcode user-facing text, " +
        "always route through IStringLocalizer<AppStrings>. Then retry this exact edit. " +
        "This gate fires once per session per product per file category.")
}

[ ] Initialize root entry node (AGENTS.md).
[ ] Define routing matrix mapping file extensions to required rules.
[ ] Isolate module-specific rules into distinct files.
[ ] Establish definitive rule repository (docs/) as the single source of truth.
[ ] Define skill triggers with explicit operational pre-conditions.
[ ] Deploy interceptor script to halt execution and mandate rule review.
[ ] Restrict tool-specific directories (.claude, .github) to pointer artifacts.

Enjoy it: CrystaCode

MCP for .NET: AI Agents That Can Actually Do Things

Hamed Hajiloo — Wed, 18 Feb 2026 08:08:02 +0000

Crysta is an AI app where you can build your own AI agents for real business use.

What makes it powerful is this: you are not limited to the default behavior of a chatbot.
You can connect different MCP servers and give your agent practical capabilities like scheduling, reservations, and data access.

In short, Crysta helps you build an AI agent that does more than talk, it can actually get work done.

What Users Can Connect

With MCP, an agent can connect to tools such as:

Google Calendar workflows
Reservation and scheduling systems
Business data tools exposed through MCP
Knowledge tools like DeepWiki (through MCP)

So instead of only answering a request like "book a meeting," the agent can actually do it through a connected tool.

Why This Matters for .NET Developers

MCP gives .NET developers a straightforward way to add real capabilities to an AI agent without building every integration yourself. Instead of wiring each API directly into your app, you connect MCP‑compatible tools and let the agent use them through the same function‑calling flow.

This leads to two big benefits:

Faster development: new features come from adding MCP tools, not writing new integrations.
Cleaner architecture: your agent grows by adding tools, not by adding more prompt logic or custom glue code.

How We Built It (High Level)

We kept the flow simple:

User adds an MCP server link to an agent.
System validates the link and reads tool metadata.
Connected MCP tools become part of that agent’s available actions.
During chat, the model can call those tools when needed.
We track failures and connection health so users can fix broken links quickly.

Packages We Use for This

These are the key packages behind this MCP workflow:

ModelContextProtocol
Microsoft.Extensions.AI
Microsoft.Extensions.AI.OpenAI
Azure.AI.OpenAI

This combination gives us MCP tool discovery plus a solid function-calling pipeline in .NET.

Small Code Examples (Based on Our Code)

Here’s a sample snippet that reflects the structure we use in our production pattern.

1) MCP client + validation service

using ModelContextProtocol.Client;

public class McpServerService : IMcpServerService
{
    public async Task<StoredMcpServer> ValidateAndGetMcpInfoAsync(string mcpUrl)
    {
        if (!Uri.TryCreate(mcpUrl, UriKind.Absolute, out _))
        {
            return new StoredMcpServer { IsValid = false, ErrorMessage = "Invalid URL format" };
        }

        try
        {
            var transport = new HttpClientTransport(
                new HttpClientTransportOptions { Endpoint = new Uri(mcpUrl) },
                loggerFactory: null);

            var client = await McpClient.CreateAsync(transport);
            var serverInfo = client.ServerInfo;

            return new StoredMcpServer
            {
                Url = mcpUrl,
                Title = serverInfo?.Name ?? "Unknown MCP Server",
                Description = serverInfo?.Title ?? "No description available",
                AddedDate = DateTime.Now,
                IsValid = serverInfo is not null
            };
        }
        catch (Exception ex)
        {
            return new StoredMcpServer { IsValid = false, ErrorMessage = ex.Message };
        }
    }

    public async Task<McpClient> CreateClientAsync(string mcpUrl, CancellationToken cancellationToken = default)
    {
        var transport = new HttpClientTransport(
            new HttpClientTransportOptions { Endpoint = new Uri(mcpUrl) },
            loggerFactory: null);
        return await McpClient.CreateAsync(transport);
    }
}

2) Load MCP tools from agent skills (runtime)

using Microsoft.Extensions.AI;
using ModelContextProtocol.Client;

private async Task<List<AIFunction>> GetMcpToolsAsync()
{
    if (interactiveAgent?.Skills == null) return [];

    var allTools = new List<AIFunction>();
    using var scope = ServiceScopeFactory.CreateScope();
    var mcpServerService = scope.ServiceProvider.GetRequiredService<IMcpServerService>();

    foreach (var skill in interactiveAgent.Skills)
    {
        if (skill.SkillType != SkillType.MCP) continue;
        if (skill.SkillJson is null) continue;

        var check = await mcpServerService.ValidateAndGetMcpInfoAsync(skill.SkillJson);
        if (!check.IsValid) continue;

        var client = await mcpServerService.CreateClientAsync(skill.SkillJson);
        var tools = await client.ListToolsAsync();
        allTools.AddRange(tools);
    }

    return allTools;
}

3) Attach MCP tools to `Microsoft.Extensions.AI` chat pipeline

using System.ClientModel;
using Azure.AI.OpenAI;
using Microsoft.Extensions.AI;

var azureChatClient = new AzureOpenAIClient(
    new Uri(endpoint),
    new ApiKeyCredential(apiKey))
    .GetChatClient(deployment)
    .AsIChatClient();

var mcpTools = await GetMcpToolsAsync();

var chatClient = new ChatClientBuilder(azureChatClient)
    .ConfigureOptions(options =>
    {
        options.Tools ??= [];
        foreach (var tool in mcpTools)
        {
            options.Tools.Add(tool);
        }
    })
    .UseFunctionInvocation(c => c.AllowConcurrentInvocation = true)
    .Build();

This is the exact idea we use: validate MCP links, discover tools, then pass those tools into the chat client so the agent can call them.

Closing

MCP moved our product from "AI that answers" to "AI that acts."

That is the difference users notice immediately.

If you want to see the end result, check it here: https://crystacode.ai

How I Fixed a Web Audio Echo Problem with a 5-Second Delay

Hamed Hajiloo — Sat, 01 Nov 2025 14:28:10 +0000

How I fixed a web audio echo problem with a 5-second delay

if you want to do anything with audio in the browser, you’ll have to deal with the Web Audio API. it’s what powers everything — from music apps to AI voice chats.

recently I was building a real-time user ↔ AI voice conversation app CrystaCode.ai.

everything worked fine except one weird thing:

👉 during the first few seconds of each conversation, the AI’s voice got picked up by the mic. after that? no echo at all.

I spent days trying everything different routing, gain nodes, worklets, custom dsp, RNNoise — nothing fixed it. then, out of frustration, i added one line:

await new Promise(res => setTimeout(res, 5000));

between starting the mic and sending audio to the AI. and boom — echo gone forever.

wait... why did this work?
when you call:

navigator.mediaDevices.getUserMedia({
  audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true }
});

the browser gives you a mic stream with built-in acoustic echo cancellation (aec).
that aec runs natively inside chrome, firefox, safari, or edge usually the same code used in webrtc (like webrtc::EchoCanceller in chrome).

the browser AEC works like this:

it watches what’s playing from your speakers
it listens to your microphone at the same time
it learns the relationship between the two — basically: “when I play this, the mic hears that”
it builds a model of your room acoustics and device path
after a few seconds, it knows how to subtract the speaker sound from the mic signal

so it needs time to adapt — normally 2–5 seconds. during that time, the AEC hasn’t finished learning yet, so a little bit of echo leaks through. the bug wasn’t a bug

my web audio code was fine. the browser just needed time to adapt.

by delaying the start of sending mic audio to the ai for 5 seconds, I let the AEC finish adapting. after that, no more echo.

why browsers behave like this

browser AEC uses adaptive algorithms. they constantly adjust to changing acoustics speaker position, device, user movement, etc.

so, every time you start the mic, the algorithm resets and starts learning again. the first few seconds are a "training phase". if you stream mic audio too early, it still contains echo. after it converges — everything becomes clean.

TL;DR

problem: ai voice was picked up by mic in first seconds
reason: browser AEC needs time to adapt
fix: delay sending mic data for ~5s before starting conversation

More info

MDN: Web Audio API
MDN: getUserMedia constraints