AI-driven software development today divides into two complementary but distinct patterns: agentic loop programming (autonomous, iterative agents) and Spec‑Driven Development (SDD, spec-as-source-of-truth). Both appear in modern toolchains: agentic loops power autonomous workflows and multi‑step reasoning, while SDD tames AI generation by anchoring code to machine‑readable contracts. This post compares the approaches, highlights tradeoffs, and provides compact, runnable C# examples you can adapt.

Short definitions

• Agentic loop programming: goal → orchestrator →reason/plan → act (tools, etc.) → observe → orchestrator, loop where an LLM-driven agent runs multiple cycles, calls tools, observes results, and continues until the goal is met. Useful for autonomy, complex orchestration, and long‑horizon tasks.
• Spec‑Driven Development (SDD): the machine‑readable spec is the primary artifact (single source of truth). Code (or tests) is generated/derived from the spec; at the end validates that implementations match the spec. SDD improves traceability, auditability, and reduces drift in AI-generated code.

When to choose which

• Choose agentic loops when you need autonomy or multi‑step decision-making (automated repair, orchestration, continuous monitoring). Expect some non‑determinism but gain flexibility and problem-solving capability.
• Choose SDD when determinism, correctness, and traceability matter (regulated domains, contracts, API-first development). SDD reduces drift and aids audit and compliance.

Agentic loop: risks and hardening
Main risks: goal drift, infinite loops, runaway cost/latency, security/tool misuse, auditability gaps. Mitigations: typed tool I/O, explicit stop conditions, iteration/cost caps, human checkpoints for high‑impact actions, rich logging/auditing, and canary testing. These patterns are essential before deploying agents to production

Spec‑Driven Development: risks and hardening
Main risks: over‑specification and maintenance burden; outdated or low‑quality specs yield brittle generation. Mitigations: invest in good spec discipline, machine‑readable formats (JSON, OpenAPI), auto‑derived tests, gates, and schema validation. SDD improves auditability because the spec itself is the contract.

Concrete C# examples
Below are compact patterns you can drop into a sandbox. The LLM calls are mocked — replace them with your LLM client (OpenAI/Anthropic) in real projects.

1. Agentic loop pattern (C#)
   Purpose: show a simple agent loop that (a) reasons via LLM placeholder, (b) executes typed tools, (c) observes and updates memory, and (d) uses explicit stop conditions.

Key elements: ITool contract, AgentContext (memory), clear stop conditions, max iterations, and typed tool outputs for safer parsing.

Code (runnable pattern)

using System;
using System.Threading.Tasks;

public interface ITool<TInput, TOutput>
{
    Task<TOutput> ExecuteAsync(TInput input);
}

// Example tool: shell-like task
public class ShellTool : ITool<string, string>
{
    public Task<string> ExecuteAsync(string input)
    {
        // Simulate work
        return Task.FromResult($"Shell executed: {input}");
    }
}

public class AgentContext
{
    public string Goal { get; }
    public int Iteration { get; set; }
    public string Memory { get; set; }
    public decimal CostSoFar { get; set; }

    public AgentContext(string goal)
    {
        Goal = goal; Iteration = 0; Memory = ""; CostSoFar = 0m;
    }
}

public class Agent
{
    private readonly ITool<string, string> _tool;
    private readonly int _maxIterations;
    private readonly decimal _maxCost;

    public Agent(ITool<string, string> tool, int maxIterations = 10, decimal maxCost = 10.0m)
    {
        _tool = tool; _maxIterations = maxIterations; _maxCost = maxCost;
    }

    // Placeholder for LLM call; replace with actual client.
    private Task<string> CallLLMAsync(string prompt)
    {
        // Very simple mock that alternates between calling tool and finishing.
        if (prompt.Contains("satisfied", StringComparison.OrdinalIgnoreCase))
            return Task.FromResult("DONE");
        return Task.FromResult("ACTION:call_tool INPUT:run-step");
    }

    public async Task RunAsync(AgentContext ctx)
    {
        while (true)
        {
            if (ctx.Iteration >= _maxIterations)
            {
                Console.WriteLine("Stopping: reached max iterations.");
                return;
            }

            if (ctx.CostSoFar >= _maxCost)
            {
                Console.WriteLine("Stopping: reached cost budget.");
                return;
            }

            ctx.Iteration++;
            var observation = $"Goal:{ctx.Goal}; Memory:{ctx.Memory}; Iteration:{ctx.Iteration}";
            var plan = await CallLLMAsync($"Observe: {observation}\nDecide: is goal satisfied?");
            Console.WriteLine($"[LLM] plan={plan}");

            if (plan.StartsWith("DONE", StringComparison.OrdinalIgnoreCase))
            {
                Console.WriteLine("Agent: Goal satisfied.");
                return;
            }

            if (plan.Contains("ACTION:call_tool", StringComparison.OrdinalIgnoreCase))
            {
                // Parse input token (naive here)
                var toolInput = "run-step";
                var toolResult = await _tool.ExecuteAsync(toolInput);
                Console.WriteLine($"[Tool] {toolResult}");

                // Update memory and cost (mock cost per tool call)
                ctx.Memory += $" | iter{ctx.Iteration}:{toolResult}";
                ctx.CostSoFar += 1.0m;

                // Ask LLM to evaluate the observation
                var eval = await CallLLMAsync("Was result satisfactory?");
                if (eval.StartsWith("DONE", StringComparison.OrdinalIgnoreCase))
                {
                    Console.WriteLine("Agent: confirmed success after tool execution.");
                    return;
                }
            }
            else
            {
                Console.WriteLine("Agent: no actionable plan, stopping to avoid stray behavior.");
                return;
            }
        }
    }
}

// Example run
public static class Program
{
    public static async Task Main()
    {
        var agent = new Agent(new ShellTool(), maxIterations: 5, maxCost: 3.0m);
        var ctx = new AgentContext("Add feature X and pass unit tests");
        await agent.RunAsync(ctx);
    }
}

Notes on hardening:

• Replace CallLLMAsync with structured prompts and parse JSON responses. Use typed JSON schemas for actions.
• Add RBAC for tools that access network or shell. Log each step with timestamps and full inputs/outputs for audit.
• Implement deciders that prevent repeated cycles (dedup memory) and ephemeral human checkpoints when necessary.

2. Spec‑Driven Development pattern (C#)
   Purpose: show a minimal SDD flow: a machine‑readable spec (JSON) describes endpoints; a generator creates a service skeleton and a test scaffold. In production, an AI can implement methods from the spec and CI runs auto‑derived tests to enforce the contract.

Example Spec (spec.json)

{
  "service": "UserService",
  "description": "Create and get users",
  "endpoints": [
    { "name": "CreateUser", "input": { "name":"string","email":"string" }, "output": { "id":"guid" } },
    { "name": "GetUser", "input": { "id":"guid" }, "output": { "name":"string","email":"string" } }
  ],
  "constraints": {
    "email": "must be valid format",
    "name": "non-empty"
  }
}

Generator and test scaffold (simplified)

using System;
using System.IO;
using System.Text.Json;
using System.Text;

public class SpecGenerator
{
    public static void Generate(string specPath, string outDir)
    {
        var json = File.ReadAllText(specPath);
        using var doc = JsonDocument.Parse(json);
        var root = doc.RootElement;
        var serviceName = root.GetProperty("service").GetString();

        var sb = new StringBuilder();
        sb.AppendLine("using System;");
        sb.AppendLine("namespace Generated {");
        sb.AppendLine($"  public class {serviceName} {{");

        foreach (var ep in root.GetProperty("endpoints").EnumerateArray())
        {
            var name = ep.GetProperty("name").GetString();
            sb.AppendLine($"    // Auto-generated: {name} - implement per spec");
            sb.AppendLine($"    public object {name}(object input) => throw new NotImplementedException();");
        }

        sb.AppendLine("  } }");

        Directory.CreateDirectory(outDir);
        File.WriteAllText(Path.Combine(outDir, $"{serviceName}.cs"), sb.ToString());

        // Test scaffold example
        var test = new StringBuilder();
        test.AppendLine("using Xunit;");
        test.AppendLine($"public class {serviceName}Tests {{");
        test.AppendLine("  [Fact]");
        test.AppendLine($"  public void CreateUser_ShouldReturnId() => throw new NotImplementedException();");
        test.AppendLine("}");
        File.WriteAllText(Path.Combine(outDir, $"{serviceName}.Tests.cs"), test.ToString());
        Console.WriteLine(\"Generated files in: \" + outDir);
    }

    public static void Main(string[] args)
    {
        Generate(\"spec.json\", \"out\");
    }
}

How AI fits in SDD:

• The spec is authoritative. An AI (or human) generates code that implements the spec. Tests are generated from the spec (asserting types, constraints, and examples). CI runs tests; failures trigger regeneration or human review. This establishes traceability and reduces drift

Making SDD production-quality

• Use a formal schema (OpenAPI, JSON Schema, protobuf). Generate strong typed models (C# records/classes) from the spec. Use auto‑derived contract tests that validate constraints (email format, non-empty name). For more advanced workflows, integrate Roslyn-based analyzers that flag divergences at compile time, and store specs in a versioned repository for audit.

Practical comparisons and recommendations

• Observability & Auditability
  • Agentic loop: requires explicit structured logging, typed tool outputs, and a chain-of-thought or step tracing. Without this, auditing is difficult.
  • SDD: natural audit trail because the spec is the contract; tests and commit history show intent and evidence.
• Speed vs Overhead
  • Agentic loops can rapidly iterate and adapt but add runtime complexity (guardrails, tool contracts).
  • SDD requires upfront work on a machine‑readable spec but reduces downstream rework and improves compliance.
• Typical real-world use-cases
  • Agentic loops: automated bug-fix agents, cloud orchestration that runs multi-step operations, autonomous data pipelines, or customer support agents that call external APIs.
  • SDD: API-first microservices in finance/healthcare, contract-based integrations, teams generating implementations from an agreed, audited spec.
• Combining the two (hybrid patterns)
  • Use SDD to define critical contracts and expose typed tool interfaces to agents. Agents operate inside the guardrails defined by the spec. For example, an agent that patches code should only call tools whose inputs/outputs are specified in SDD artifacts. This approach balances autonomy with control and auditability.

Conclusion
Agentic loop programming and Spec‑Driven Development serve different needs. Agentic loops buy autonomy and multi-step problem solving. SDD buys determinism, traceability, and compliance. In practice, the strongest architectures blend them: use SDD to define and enforce the boundaries and contracts, and deploy agentic loops inside those boundaries to perform autonomous tasks. The C# patterns above give you a starting point: a simple agent loop pattern hardened with stop conditions and typed tools, and an SDD generator that shows how specs map to code and tests

Note: Much of the code was written by AI and is offered as is (AI makes mistakes, so proceed with caution). The text was also written by AI but significantly edited by me.

Soooo, this is the very first in a series. I’m finding my way, stumbling in the dark, so some of this may be a bit simplistic—but I believe it is correct as far as it goes. Remember, however, that the first draft of this post was written by AI. I’ve edited it, but your mileage may vary.

Here’s a thought experiment. Imagine having an agent that keeps trying fixes until a web service stays healthy—retrying configuration changes, re-checking status, and stopping only when a health check returns OK or a safety limit is reached. That behavior—automatic, bounded repetition with an evaluation step between attempts—is exactly what loop programming enables in modern agentic AI. This post explains the pattern, why it matters, and how to implement it in C# using the Microsoft Agent Framework (MAF) concepts.

One-sentence takeaway
Loop programming = agent acts → observes → evaluates → repeats (until accepted or bound). Use MAF’s loop primitives (loop wrapper or middleware + evaluators) to implement this pattern safely in .NET.

Why loop programming matters

• Iterative refinement: reduce hallucinations by asking the model to rework outputs until they meet quality criteria.
• Multi-step tasks: break complex tasks into incremental attempts (repair, check, retry).
• Automation & robustness: automatically retry flaky tools with idempotency and backoff, or orchestrate multi-tool workflows until success.
• Cost/latency tradeoffs: each iteration consumes time and tokens—a deliberate loop strategy balances accuracy and cost.

Core MAF loop terms

• Base agent / client: This is the model wrapped as an agent (an abstraction that receives requests and produces responses).
• Loop wrapper or middleware: A piece that re-invokes the base agent automatically, applying evaluator logic between iterations.
• Evaluator: A component that inspects the previous response and returns Continue or Stop. Examples:
  • Marker-based evaluator: stop when the output contains a specific marker (e.g., “DONE”).
  • Judge evaluator: ask an auxiliary judge model to say whether the output is acceptable.
  • Custom evaluator: your own logic that checks outputs, tool results, or external state.
• Bounds: MaxIterations, timeouts, and cancellation tokens—mandatory to avoid runaway loops.
• AgentRequest: the input to an agent (prompt, tools, options).
• AgentResponse: the output (text, structured data, tool results).

Minimal, runnable-style C# example
Below is a full Program.cs and a simple csproj. The example uses a completion-marker evaluator (“DONE”) and a MaxIterations bound. It is a bit brain-dead, but it will give you a sense of how to string one of these together.

using System;
using System.Threading;
using System.Threading.Tasks;

using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Evaluators;
using Microsoft.Agents.AI.OpenAI.Clients;

class Program
{
   static async Task Main(string[] args)
   {
      // Read API key (set as env var)
      string? apiKey =     Environment.GetEnvironmentVariable("OPENAI_API_KEY");
      if (string.IsNullOrEmpty(apiKey))
      {
         Console.WriteLine("Set OPENAI_API_KEY environment variable and re-run.");
         return;
      }
 // 1) Create provider client (provider-specific)
    var openAiClient = new OpenAiProviderClient(new OpenAiOptions { ApiKey = apiKey });

    // 2) Convert provider client to an agent abstraction
    AIAgent baseAgent = openAiClient.AsAIAgent();

    // 3) Create a simple marker evaluator that stops when "DONE" appears
    var evaluator = new CompletionMarkerLoopEvaluator("DONE");

    // 4) Wrap the base agent with loop behavior and bounds
    var loopOptions = new LoopAgentOptions { MaxIterations = 5 };
    AIAgent loopAgent = new LoopAgent(baseAgent, evaluator, loopOptions);

    // 5) Prepare request
    var request = new AgentRequest
    {
        Prompt = "Summarize this paragraph and keep refining until you append DONE:\n\n" +
                 "The quick brown fox jumps over the lazy dog. This sentence includes all the letters of the English alphabet."
    };

    // 6) Use a timeout for safety
    using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
    try
    {
        AgentResponse response = await loopAgent.InvokeAsync(request, cts.Token);
        Console.WriteLine("Final response:\n" + response.Text);
    }
    catch (OperationCanceledException)
    {
        Console.WriteLine("Operation timed out or was canceled.");
    }
}
}

How to adapt this to the real MAF packages

• Install packages
  • dotnet add package Microsoft.Agents.AI
  • dotnet add package Microsoft.Agents.AI.OpenAI
• The logical steps are always pretty much the same: build a base agent, choose an evaluator, apply loop wrapper or middleware, and call it.

Designing better evaluators (AI judge and custom evaluator)

Marker evaluator (simple)

• Pros: deterministic and cheap.
• Cons: brittle.

AIJudge evaluator (higher quality)

• Pattern: after each iteration, call a small judge prompt that returns YES/NO and a short reason. Use a very explicit evaluation prompt to reduce ambiguity.
• Example judge prompt (send as a separate small completion request):
  “You are a strict grader. Given the task: [task description]. Given the model response: [response]. Is the response acceptable? Answer EXACTLY YES or NO followed by a short reason.”

Custom evaluator pattern (checks content + side effects)

• Inspect response text for task markers (like DONE) and for required structured outputs.
• Check external state (database, API) to determine if the side effect succeeded.
• Optionally consult a judge model only when heuristic checks are inconclusive.

Sample custom evaluator

public class KeywordOrJudgeEvaluator : ILoopEvaluator
{
private readonly string _stopKeyword;
private readonly AIAgent? _judgeAgent;

public KeywordOrJudgeEvaluator(string stopKeyword, AIAgent? judgeAgent = null)
{
    _stopKeyword = stopKeyword;
    _judgeAgent = judgeAgent;
}

public async Task<LoopDecision> EvaluateAsync(AgentResponse lastResponse, CancellationToken ct)
{
    if (lastResponse.Text?.Contains(_stopKeyword, StringComparison.OrdinalIgnoreCase) == true)
        return LoopDecision.Stop();

    if (_judgeAgent != null)
    {
        var judgeRequest = new AgentRequest
        {
            Prompt = $"Is the following response acceptable? Answer YES or NO.\n\nResponse:\n{lastResponse.Text}\n\nCriteria: [list your criteria]"
        };
        var judgeResponse = await _judgeAgent.InvokeAsync(judgeRequest, ct);
        if (judgeResponse.Text.Trim().StartsWith("YES", StringComparison.OrdinalIgnoreCase))
            return LoopDecision.Stop();
    }

    return LoopDecision.Continue();
}
}

Practical safety and production best practices

• Always set MaxIterations. Decide MaxIterations based on expected task complexity (2–5 for refinement tasks, more for longer repair flows).
• Use a wall-clock timeout (CancellationTokenSource) to cap total runtime.
• Log each iteration: input prompt, model output, evaluator decision, iteration duration, and any tool calls.
• Be idempotent for side-effecting tool calls: include an idempotency key or track completed steps to avoid duplicate side effects.
• Use backoff and limited retries for transient tool failures.
• Consider human-in-the-loop for high-risk operations.
• Capture metrics: iterations-per-task, average cost per task, success rate after N iterations.

Exponential backoff snippet

int attempt = 0;
while (attempt < maxRetries)
{
   attempt++;
   try { callTool(); break; }
   catch (TransientException)
   {
      await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt)));
   }
}

Cost and latency tradeoffs

• Each loop iteration = another model call (cost + latency). If you expect 2–3 iterations on average, estimate cost = baseCost × expectedIterations + judgeCost (if used).
• Use marker evaluators when iterations are cheap and you can control the prompt reliably; use judge evaluators when marker brittleness is likely.
• For low-latency needs, constrain MaxIterations or move part of the evaluation logic to a fast heuristic.

Debugging, testing, and observability tips

• Unit test evaluators with mocked AgentResponse objects. Keep evaluator logic pure when possible so it’s easy to test.
• Mock provider clients for integration tests so you can simulate iteration sequences and failures deterministically.
• Log a concise iteration record: {iteration, promptFingerprint, outputHash, evaluatorDecision, duration, costEstimate}.
• Add correlation IDs across iterations for traceability.

Troubleshooting common failure modes

• Marker never appended → verify prompt instruction clarity, or switch to judge evaluator.
• Judge flip-flops (YES/NO across iterations) → add hysteresis: require two consecutive YES judgments, or use a heuristic plus judge.
• Side effects duplicated → make tools idempotent or track operation IDs.
• Loop stalls (no progress) → add progress metrics and a stuck detection rule (stop if no semantic change after N iterations).

Real-world scenario examples

• Document extraction and QA: agent extracts structured data, runs validators, requests corrections until extraction passes validators or MaxIterations reached.
• Customer support automation: agent composes reply drafts and refines them until a judge model or human reviewer marks them acceptable.

Conclusion and next steps
Loop programming is a practical, powerful pattern for agentic AI: agent acts, inspects results, evaluates, and repeats — but only when bounded and observable. The Microsoft Agent Framework offers loop wrapper and evaluator patterns to implement this safely; adapt the example above to your MAF version and provider.

BlogWriter

My demo program, BlogWriter, uses a much more deterministic approach. While the author does pass its draft to the reviewer for evaluation, and they do create a small loop, a true looping approach would, perhaps, return better results. Something to try.

More to come soon…

• Marks videos as started or completed
• Displays your progress and total time for video, along with date and other meta-data
• Single click on card displays details
• If details contain chapters, clicking on a chapter brings you there
• Double-click on video and go to where you left off
• Mark videos as important (and see all important videos listed together)
• Delete videos from your list to avoid clutter
• Drag and drop lists of videos to reorder
• Drag and drop cards within list

The source offers two versions: Desktop and Web. Please read CONTRIBUTING.md before contributing to the project.

For you to use this, I will need to add your email to the list of test users. Please contact me at jesseliberty@gmail.com if you are going to be submitting pull requests.

Note: Much of the code was written by AI and is offered as is (AI makes mistakes, so proceed with caution). For more, please read the Readme.md file.

However, Bruno Capuano (Microsoft) and I went over this for my latest video with him. His reaction was that what I was doing was “right” but that I was working too hard, doing things that the Microsoft.Extensions.AI.Templates would do for me—or at least make simpler. He pointed me to the quickstart for AIChatSample.

The analysis in the quickstart is out of date, and there are significant changes. Here is an analysis of the latest version of the code. You can get the code itself from the quickstart, but note that I use llama.cpp rather than Ollama.

The rest of this post walks through the RAG implementation in AIChatSample, a Blazor chat application that uses OpenAI-compatible endpoints provided by llama.cpp. The emphasis is on the full path: configuring separate chat and embedding clients, ingesting and chunking documents, saving vectors in SQLite, retrieving relevant chunks, and turning those results into visible citations.

The application at a glance

The main pieces are registered in Program.cs. The app creates an IChatClient for conversation and an IEmbeddingGenerator<string, Embedding<float>> for vector embeddings. Both are built from configured endpoint and model values using the OpenAI .NET client adapters. Although the clients use the same API style, they do different jobs and may run on separate llama.cpp servers: the chat endpoint generates responses and handles tool calls, while the embedding endpoint converts text into vectors.

That distinction matters. RAG needs embeddings when documents are prepared and again when a user query is searched. The chat model is not the search index, and a chat-only server cannot replace the embedding service. This sample configures an all-MiniLM embedding model that produces 384-dimensional vectors. The vector schema declares that same dimension, so the model and stored collection must remain compatible.

Program.cs also registers a SQLite vector store and a collection for IngestedChunk, then registers DataIngestor and SemanticSearch as singleton services. The document source is the app’s wwwroot\Data directory. This keeps the sample’s architecture compact: the same directory supplies documents to the ingestion pipeline and later supports the UI’s links back to source files.

Stage one: read and normalize documents

The RAG pipeline begins when a search is needed, not when the web host starts. In Chat.razor, the assistant is offered a LoadDocuments tool and instructed to use it before searching. The tool calls SemanticSearch.LoadDocumentsAsync, which starts the ingestion task the first time and retains that task for later calls. This means repeated tool invocations share the same load operation rather than starting a new one each time.

DataIngestor.IngestDataAsync assembles the ingestion pipeline from three parts: a reader, a chunker, and a vector-store writer. It scans the configured directory using the *.* search pattern. The custom DocumentReader delegates Markdown to the Markdown reader and PDFs to PdfPigReader. Markdown is assigned the text/markdown media type; PDFs are handled by the PDF reader. Unsupported media types fail explicitly rather than being silently treated as plain text.

The PDF reader opens each document with PdfPig, walks through its pages, extracts letters, groups them into words, and then groups words into text blocks. Each block becomes a paragraph element in a section labeled with the PDF page number. That page-aware structure gives the ingestion pipeline organized text to work with instead of treating a PDF as a single opaque binary file. The document reader also normalizes fully qualified identifiers to paths relative to the data directory, which is useful later when a result needs to identify its source document.

Stage two: split the text and embed it

Searching an entire book or long report as one record would be imprecise and could exceed what is useful to pass to a model. AIChatSample therefore uses SemanticSimilarityChunker in DataIngestor. The chunker uses the configured embedding generator and a tokenizer (TiktokenTokenizer configured for gpt-4o) to create manageable pieces. Semantic chunking aims to keep related content together, rather than cutting text only at arbitrary fixed character boundaries. The exact chunking behavior is provided by the ingestion library, while the app supplies the model and tokenizer it should use.

Each resulting chunk is represented by IngestedChunk. Its fields capture a unique key, the source DocumentId, the chunk’s Text, and an optional Context field. The Vector property returns the chunk text, which allows the vector-store integration to generate an embedding from that text. The vector property is annotated as a 384-dimensional vector with cosine distance. In effect, each stored item contains both searchable semantic representation and the original text needed to give the language model actual evidence.

The VectorStoreWriter is configured with the collection name, dimension count, and distance function from the record type. It writes the pipeline’s chunks into the SQLite vector store. The writer is set to non-incremental ingestion, so the application explicitly does not configure incremental ingestion for this pipeline. Persisting the collection locally means later searches can query the indexed chunks without reconstructing an in-memory index for every question.

Stage three: find relevant chunks

When the model calls the Search tool, Chat.razor passes the user’s search phrase and an optional filename filter to SemanticSearch.SearchAsync. That method first awaits LoadDocumentsAsync, ensuring ingestion is complete before vector search proceeds. The vector collection then searches for the phrase and asks for up to the requested number of results. If a document ID was supplied, a filter restricts matches to that document; without one, search spans the collection. The chat tool requests a maximum of five results.

Conceptually, the embedding service maps the query into the same vector space as the document chunks. The vector store compares that query vector with stored chunk vectors using cosine distance and returns the nearest matches. The application returns the matching records, including their source document IDs and text. This is semantic retrieval: the query can find conceptually similar passages even when they do not repeat the exact wording of the question.

The top results are not themselves the final answer. They are evidence to be passed back to the model. The Search tool formats each result as a small XML-like fragment containing a filename and the text. This gives the model explicit source boundaries and the passage content it can use when drafting a response.

Stage four: let the model use tools and answer

The chat page constructs a system prompt that restricts the assistant to questions about retrieved information. It tells the model to load the documents, use search, and cite search results. In OnInitialized, the page exposes the LoadDocumentsAsync and SearchAsync methods as AI functions through AIFunctionFactory. Program.cs wires function invocation into the chat client, so the model can request these application functions during a conversation.

This is an important distinction from a design where the app blindly retrieves a fixed set of chunks for every incoming message. Here, the model can first decide to load and search, and it can provide a search phrase and optionally a filename. The UI gives it tool descriptions and argument descriptions to guide those decisions. Once the tool returns passages, the model can compose a natural-language answer based on them. It is still the model that writes the response; retrieval supplies relevant, external context.

Responses stream into the Blazor page through GetStreamingResponseAsync. The page accumulates text updates and also keeps non-text content such as function-call information in the conversation. The UI can therefore show progress such as document loading or the current search phrase while the assistant works, rather than waiting for the entire response before showing anything.

Stage five: citations connect an answer to its source

The prompt asks the model to finish with citation tags in a particular format, using a short exact quote from the retrieved result. ChatMessageItem looks for those tags after a response is complete. It extracts the filename and quote, then renders each as a ChatCitation component. The component creates a link to an appropriate viewer: Markdown opens in the Markdown viewer with a text-fragment target, while PDF opens in the PDF viewer with a search fragment.

This makes citations more than decorative labels. A reader can follow the source filename and quote back to the underlying document. The prompt’s five-word quote limit is a small convention that encourages concise evidence anchors, while the actual source passage remains available to the model during answer generation.

There are practical limits to note. The citation is generated by the model and parsed from its text, so the prompt guides the format but does not by itself guarantee that every quote is valid or that the answer is fully supported. Retrieval quality also depends on document extraction, chunk boundaries, embedding-model suitability, and the number of results. For production use, teams often add checks that verify a cited quote appears in the retrieved text, evaluate retrieval quality against representative questions, and add metadata filters for access control or document categories.

How to run and evolve the RAG sample

The README describes configuring two llama.cpp servers: one chat-compatible model and one embedding model that supports the OpenAI-compatible embeddings endpoint. The app needs both endpoints reachable. The collection schema in IngestedChunk expects 384-dimensional embeddings; changing the embedding model may require updating that dimension, deleting and recreating the local vector database, and re-ingesting the documents so query vectors and stored vectors remain compatible.

To add another document type, extend DocumentReader with a reader for its media type and decide how its structure should be represented as sections and elements. To tune retrieval, measure the quality of chunking, consider metadata such as page numbers and titles, and test whether the chosen result count gives the chat model enough evidence without overwhelming the prompt. To make citations more precise, preserve useful location metadata through ingestion and include it in the result returned to the model.

The central idea is straightforward: read documents into structured text, split that text into semantically useful chunks, embed and persist the chunks, retrieve the nearest matches for a query, and give those passages to a model that can answer and cite them. AIChatSample implements each step in a small set of services and connects the steps through model-invoked tools. Follow one question through those stages and RAG becomes less of a buzzword and more of a concrete data flow—from files in Data to an answer with a trail back to its evidence.

This analysis was composed by BlogWriter and then edited by me. Please note that AIs can make errors and this analysis is offered as is.

What you’ll get (artifacts shown in this guide)

• A consistent extension folder layout you can copy into a project-level .specify/extensions/ directory for local testing. (If your environment uses a different extension directory, replace .specify accordingly.)
• Full extension.yml manifest.
• A slash command file: addon/commands/speckit.extn.myfeature.md.
• A lifecycle hook descriptor: addon/hooks/after-plan.yml and platform run wrappers.
• A small C# console app (MyFeatureRunner) that reads a spec path and writes structured JSON to stdout.
• Install scripts (install.sh, install.ps1) and OS wrappers (run.sh/run.ps1) to select the right binary.
• A GitHub Actions workflow that builds platform binaries and packages a ZIP for publishing.
• Tests (xUnit) that exercise the analyzer logic (no Python anywhere).

Step 0 — conventions & a note on paths

• I’ll use “Spec Kit” consistently here and show the local extension install path as .specify/extensions/ (this is the common convention in community examples). If your tooling uses a different folder, replace .specify accordingly.
• Slash command namespace convention: /speckit.extn..* — follow this for discoverability.
• Hooks use placeholders like {{spec.path}}; confirm your Spec Kit version’s exact interpolation tokens and adapt if necessary.

Step 1 — pick scope and design
Decide the minimal valuable feature for your first release. Example here:

• Add a slash command /speckit.extn.myfeature that runs an analysis on the current spec and returns structured JSON with a summary and issues. Also register an after-plan lifecycle hook that runs the same analyzer automatically when planning completes.

Define:

• Inputs: spec path (string), format (json|text), output path (optional).
• Outputs: structured JSON (summary, issues[]), exit codes.
• Failure modes: missing spec, parse errors, internal errors — map to clear exit codes and clear stderr messages.

Design outcome: a C# console app MyFeatureRunner that accepts –spec and writes JSON to stdout or an output file. Hooks call the executable with placeholders.

Step 2 — folder layout (concrete)
Create this structure (top-level folder is the extension package root):

com.yourorg.myfeature/
extension.yml
README.md
addon/
commands/
speckit.extn.myfeature.md
hooks/
after-plan.yml
templates/
mytemplate.txt
bin/
linux/
MyFeatureRunner <– published single-file linux binary
macos/
MyFeatureRunner <– published macos binary
windows/
MyFeatureRunner.exe <– published windows exe
run.sh <– wrapper selecting right binary on Unix
run.ps1 <– wrapper for Windows
src/
MyFeatureRunner/ <– dotnet project (Program.cs, Analyzer.cs, MyFeatureRunner.csproj)
tests/
MyFeatureRunner.Tests/ <– xUnit tests
examples/
sample-spec.md
install.sh
install.ps1

Notes:

• Place platform-specific published binaries under addon/bin//. Include wrapper scripts (run.sh, run.ps1) that forward args to the right binary.
• The extension.yml manifest (next) will map addon/ directories into the install target.

Step 3 — extension manifest (full example)
Put this file at the extension root as extension.yml:

name: com.yourorg.myfeature
version: 0.1.0
description: “Adds /speckit.extn.myfeature — analyzes a spec and returns structured JSON with issues.”
authors:

• name: Your Name
  email: you@example.com
  license: MIT
  tags:
• spec-analysis
• speckit
  install:
  files:
  • src: addon/commands/
    dest: commands/
  • src: addon/hooks/
    dest: hooks/
  • src: addon/templates/
    dest: templates/
  • src: addon/bin/
    dest: bin/
    hooks:
• name: after-plan
  file: addon/hooks/after-plan.yml

Explanation:

• install.files tells the Spec Kit installer how to copy files into the runtime extension directory. Keep the paths relative to the extension archive root.
• hooks are entry points to a hook descriptor file (next).

Step 4 — slash command file (full example)
File: addon/commands/speckit.extn.myfeature.md

Description: Analyze the given Spec file for structural issues and return a JSON report with “summary” and “issues”.
Inputs:

• spec-path: path to the spec file. Defaults to the current spec in the workspace if omitted.
• format: “json” (default) or “text”.
• output: optional path to write the JSON report.

Outputs:

• result (JSON):
  {
  “summary”: “string”,
  “issues”: [
  {
  “line”: 12,
  “severity”: “warning”,
  “ruleId”: “SP-001”,
  “message”: “Example issue message”
  }
  ]
  }

Examples:

• /speckit.extn.myfeature spec-path=specs/login.spec format=json
• /speckit.extn.myfeature format=text

Behavior:

• When invoked, the agent will run the extension’s hook or run wrapper that calls the C# CLI with –spec . The CLI emits structured JSON to stdout. The agent should present JSON results or a text summary as requested.

Notes:

• Keep examples explicit and provide the JSON schema so integrators know how to parse the result.

Step 5 — hook descriptor (full example)
File: addon/hooks/after-plan.yml

hook: after-plan
run: ./bin/run.sh
args:

• –spec
• “{{spec.path}}”
• –output
• “{{workspace}}/.specify/extensions/com.yourorg.myfeature/latest-report.json”
  env:
  LOG_LEVEL: info

Notes:

• run points to the wrapper script in addon/bin/ that selects the correct binary for the host OS. This simplifies cross-platform support.
• args include placeholders. Confirm the exact placeholder names in your Spec Kit version; many installations support {{spec.path}} and {{workspace}} or similar fields.

Step 6 — C# helper (full source example)
We’ll implement a small console app that performs simple analysis: counts characters and looks for TODO comments as “issues”. It’s intentionally simple but structured to be extended.

Project: src/MyFeatureRunner/MyFeatureRunner.csproj Exe net8.0 enable enable

Program.cs (src/MyFeatureRunner/Program.cs)

using System.Text.Json;
using System.Text.Json.Serialization;

public static class Program
{
  public static int Main(string[] args)
  {
    var parsed = CliArgs.Parse(args);
    if (!parsed.IsValid)
    {
      Console.Error.WriteLine(parsed.ErrorMessage);
      return parsed.ExitCode;
    }

    try
    {
        var report = Analyzer.AnalyzeFile(parsed.SpecPath);
        var options = new JsonSerializerOptions { WriteIndented = true };
        string json = JsonSerializer.Serialize(report, options);

        if (!string.IsNullOrEmpty(parsed.Output))
        {
            File.WriteAllText(parsed.Output, json);
            Console.WriteLine($"Report written to {parsed.Output}");
        }
        else
        {
            Console.WriteLine(json);
        }

        return 0;
    }
    catch (FileNotFoundException ex)
    {
        Console.Error.WriteLine(ex.Message);
        return 3;
    }
    catch (Exception ex)
    {
        Console.Error.WriteLine($"Internal error: {ex.Message}");
        return 10;
    }
}
}

CliArgs helper (embedded in same file or separate file for clarity):

internal sealed class CliArgs
{
public string SpecPath { get; init; } = string.Empty;
public string Output { get; init; } = string.Empty;
public bool IsValid { get; init; }
public string ErrorMessage { get; init; } = string.Empty;
public int ExitCode { get; init; }
public static CliArgs Parse(string[] args)
{
    if (args.Length == 0)
        return new CliArgs { IsValid = false, ErrorMessage = "Usage: MyFeatureRunner --spec <path> [--output <path>]", ExitCode = 2 };

    var dict = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
    for (int i = 0; i < args.Length; i++)
    {
        if (args[i].StartsWith("--") && i + 1 < args.Length)
        {
            dict[args[i]] = args[i + 1];
            i++;
        }
    }

    if (!dict.TryGetValue("--spec", out var spec) || string.IsNullOrWhiteSpace(spec))
        return new CliArgs { IsValid = false, ErrorMessage = "Missing required --spec <path>", ExitCode = 2 };

    dict.TryGetValue("--output", out var output);

    return new CliArgs { IsValid = true, SpecPath = spec!, Output = output ?? string.Empty };
}
}

Analyzer (src/MyFeatureRunner/Analyzer.cs)

using System.Text.Json.Serialization;

public static class Analyzer
{
  public static AnalysisReport AnalyzeFile(string path)
  {
  if (!File.Exists(path))
    throw new FileNotFoundException($"Spec not found: {path}", path); 
   var text = File.ReadAllText(path);
    var lines = text.Split(new[] { '\r', '\n' }, StringSplitOptions.RemoveEmptyEntries);

    var issues = new List<Issue>();
    for (int i = 0; i < lines.Length; i++)
    {
        var line = lines[i];
        if (line.Contains("TODO", StringComparison.OrdinalIgnoreCase))
        {
            issues.Add(new Issue
            {
                Line = i + 1,
                Severity = "warning",
                RuleId = "SP-001",
                Message = "Found TODO in spec; consider clarifying acceptance criteria."
            });
        }
    }

    return new AnalysisReport
    {
        Summary = $"Spec has {text.Length} chars, {lines.Length} non-empty lines, {issues.Count} issues.",
        Issues = issues
    };
}
}

public class AnalysisReport
{
[JsonPropertyName("summary")]
public string Summary { get; set; } = string.Empty;
[JsonPropertyName("issues")]
public List<Issue> Issues { get; set; } = new();
}

public class Issue
{
[JsonPropertyName("line")]
public int Line { get; set; }
[JsonPropertyName("severity")]
public string Severity { get; set; } = string.Empty;
[JsonPropertyName("ruleId")]
public string RuleId { get; set; } = string.Empty;
[JsonPropertyName("message")]
public string Message { get; set; } = string.Empty;
}

Design notes:

• Analyzer.AnalyzeFile is pure and easily testable. Keep the CLI thin.
• Exit codes:
  • 0 success
  • 2 argument error / usage
  • 3 not found (spec path)
  • 10 internal error

Step 7 — unit tests (xUnit)
Create src/MyFeatureRunner.Tests/MyFeatureRunner.Tests.csproj and a simple test that calls Analyzer directly (no process spawning), ensuring repeatable logic.

Sample test (src/MyFeatureRunner.Tests/AnalyzerTests.cs)

using Xunit;
using System.IO;
using System.Text.Json;

public class AnalyzerTests
{
  [Fact]
  public void AnalyzeFile_ReturnsIssuesForTODO()
  {
    var tmp = Path.GetTempFileName();
    File.WriteAllText(tmp, "Line one\nTODO: add acceptance\nAnother line\n");
    var report = Analyzer.AnalyzeFile(tmp);
    Assert.Contains("Spec has", report.Summary);
    Assert.Single(report.Issues);
    Assert.Equal("SP-001", report.Issues[0].RuleId);
  }
}

Step 8 — run wrappers and permissions
Create addon/bin/run.sh (Unix wrapper):

#!/usr/bin/env bash
set -euo pipefail
ROOT="$(cd "$(dirname "$0")" && pwd)"
PLATFORM_BIN=""
if [[ "$(uname -s)" == "Linux" ]]; then
PLATFORM_BIN="$ROOT/linux/MyFeatureRunner"
elif [[ "$(uname -s)" == "Darwin" ]]; then
PLATFORM_BIN="$ROOT/macos/MyFeatureRunner"
else
PLATFORM_BIN="$ROOT/windows/MyFeatureRunner.exe"
fi
exec "$PLATFORM_BIN" "$@"

Make it executable: chmod +x addon/bin/run.sh.

Windows wrapper addon/bin/run.ps1 (PowerShell):

param([Parameter(ValueFromRemainingArguments=$true)]$Args)
$root = Split-Path -Parent $MyInvocation.MyCommand.Path
$os = (Get-CimInstance -ClassName Win32_OperatingSystem).Caption
$exe = Join-Path $root "windows\MyFeatureRunner.exe"
& $exe @Args

Step 9 — installer scripts

install.sh:
#!/usr/bin/env bash
set -euo pipefail
EXT_ID="com.yourorg.myfeature"
DEST=".specify/extensions/$EXT_ID"
mkdir -p "$DEST"
cp -r addon "$DEST/"
cp extension.yml "$DEST/"
cp README.md "$DEST/"
echo "Installed extension to $DEST"

install.ps1 (PowerShell):
param([string]$Dest = ".specify/extensions/com.yourorg.myfeature")
New-Item -ItemType Directory -Force -Path $Dest | Out-Null
Copy-Item -Path "addon*" -Destination $Dest -Recurse -Force
Copy-Item -Path "extension.yml" -Destination $Dest -Force
Copy-Item -Path "README.md" -Destination $Dest -Force
Write-Host "Installed extension to $Dest"

Step 10 — test locally (step-by-step)

1. In a Spec Kit project:
   mkdir -p .specify/extensions
   cp -r com.yourorg.myfeature .specify/extensions/
2. Confirm files:
   ls .specify/extensions/com.yourorg.myfeature
3. Run the analyzer directly:
   dotnet run –project src/MyFeatureRunner — –spec examples/sample-spec.md Expected JSON printed or “Report written to ” if –output provided.
4. Trigger the after-plan hook via your normal Spec Kit flow (specify → plan) and confirm:
   • Hook runs and writes latest-report.json in the extension folder (or check STDOUT in logs).
   • If hook failed, inspect agent logs or the extension’s stderr captured by the CLI.

Step 11 — publishing & packaging with CI (GitHub Actions)
A sample workflow .github/workflows/publish.yml that:

• Builds and publishes single-file binaries for multiple runtimes
• Packages the extension folder into a zip
• Uploads the zip as an artifact (or creates a release)

Sample YAML (abridged for clarity):

name: Build and Package Extension
on:
push:
tags:
- 'v*..'
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
runtime: [linux-x64, linux-arm64, osx-arm64, win-x64]
steps:
- uses: actions/checkout@v4
- name: Setup .NET
uses: actions/setup-dotnet@v3
with:
dotnet-version: '8.0.x'
- name: Publish ${{ matrix.runtime }}
run: |
dotnet publish src/MyFeatureRunner -c Release -r ${{ matrix.runtime }}
-p:PublishSingleFile=true -p:PublishTrimmed=true -o ./addon/bin/${{ matrix.runtime }}
- name: Organize binaries
run: |
# move to the platform folder expected by the extension, e.g. linux->linux, osx->macos, win->windows
mkdir -p addon/bin/linux addon/bin/macos addon/bin/windows
if [[ "${{ matrix.runtime }}" == linux* ]]; then mv ./addon/bin/${{ matrix.runtime }}/MyFeatureRunner ./addon/bin/linux/MyFeatureRunner; fi
if [[ "${{ matrix.runtime }}" == osx* ]]; then mv ./addon/bin/${{ matrix.runtime }}/MyFeatureRunner ./addon/bin/macos/MyFeatureRunner; fi
if [[ "${{ matrix.runtime }}" == win* ]]; then mv ./addon/bin/${{ matrix.runtime }}/MyFeatureRunner.exe ./addon/bin/windows/MyFeatureRunner.exe; fi
- name: Zip extension
if: ${{ matrix.runtime == 'linux-x64' }}
run: |
zip -r com.yourorg.myfeature-${{ github.ref_name }}.zip extension.yml addon README.md
- name: Upload package
uses: actions/upload-artifact@v4
with:
name: extension-zip
path: com.yourorg.myfeature-${{ github.ref_name }}.zip

Notes:

• This workflow demonstrates building multiple runtimes and packaging into a zip during the linux-x64 job; you can centralize packaging in a separate job that depends on build artifacts.
• For production, consider signing artifacts and publishing to GitHub Releases or a private artifact store.

Step 12 — catalog entry & checksum
Create a catalog JSON entry referencing the ZIP URL and a checksum.

Example catalog entry:

{
"id": "com.yourorg.myfeature",
"name": "My Feature",
"version": "0.1.0",
"url": "https://example.com/com.yourorg.myfeature-0.1.0.zip",
"checksum": "sha256:abcdef123456..."
}

Generate a checksum:

• Unix: sha256sum com.yourorg.myfeature-0.1.0.zip | awk ‘{print $1}’
• PowerShell: (Get-FileHash .\com.yourorg.myfeature-0.1.0.zip -Algorithm SHA256).Hash

Step 13 — troubleshooting and debugging checklist

• Hook not executed:
  • Confirm extension.yml lists the hook and was installed to .specify/extensions//.
  • Confirm hook file path is correct and marked executable if it’s a script.
• Binary fails on host:
  • Ensure correct platform binary published or require dotnet runtime and use wrapper scripts to run dotnet MyFeatureRunner.dll.
  • Check file permissions: chmod +x on Unix binaries.
• Placeholder expansion:
  • Verify your Spec Kit installation supports placeholders like {{spec.path}}; consult your Spec Kit version docs and update hook args.
• Inspect logs:
  • Check Spec Kit or agent logs; hooks often have stdout/stderr captured — look for error messages and exit codes.
• Test locally:
  • Run the wrapper or the CLI directly with the same args the hook would send to reproduce failures.

Security & governance checklist

• Do not embed secrets inside the extension. Use environment variables or configuration files that the consumer supplies.
• Document any network calls or telemetry the extension performs.
• Prefer offline, deterministic tools; minimize external dependencies.
• Provide checksums and consider signing releases for consumers to verify integrity.
• Encourage consumers to review source before installing; keep the extension small and source-available.

Best practices & gotchas

• Use JSON for structured output; it’s easier for agents and hooks to parse than free text.
• Keep the CLI deterministic and non-interactive. Hooks execute noninteractively — no prompts.
• If you can’t ship native executables for all platforms, ship a single DLL and small launcher scripts that call dotnet MyRunner.dll; document runtime requirements.
• Consider a self-test command or endpoint (e.g., /speckit.extn.myfeature.selftest) that the user can run after install to verify everything works.

Complete end-to-end checklist (before publishing)

• extension.yml exists and maps files correctly.
• addon/commands contains command files with examples and output schema.
• addon/hooks reference run wrappers and include correct placeholders.
• addon/bin contains published artifacts for supported OSes or a DLL + run wrappers.
• README documents requirements, install, usage, and troubleshooting.
• install scripts work for Unix and Windows for local testing.
• Example spec exists and tests validate analyzer logic.
• CI builds and packages artifacts and uploads ZIP to release/host.
• Catalog entry (if publishing) includes correct URL and checksum.

Note: The initial draft of this post (and all the code) was written by BlogWriter and then
edited by Jesse Liberty. Illustrations by Copilot. Caution: LLMs make mistakes; this post is offered as is.

• A preset is a versioned package that supplies template files, CLI prompts/companion prompt text, small scripts, and tiny content changes (terminology, defaults, localization). Presets are layered at runtime; when Spec Kit resolves a template or prompt, it walks the stack, and the highest-priority “winning” file is used.
• Presets are intended for content/style/localization changes. Avoid heavy runtime logic—use Bundles or Extensions if you need stateful automation.

Step 1—design: decide scope, naming, and conventions

• Pick exactly what you will override:
  • templates/—spec, plan, or task templates (Markdown).
  • commands/—CLI command prompt text or companion .prompt.md files visible to users.
  • scripts/—shell/PowerShell scripts used by templates or lifecycle hooks.
  • small localized wording changes, default values, or doc snippets.
• Keep presets focused. One preset should do one job (branding, Spanish localization, trimmed plan structure, etc.).
• Choose an ID, version, and a default priority. Example: id = com.example.my-company-style, version = 0.1.0, priority = 8. Lower priority number = higher precedence (default is 10).
• Record author name/email and a short description in the manifest. These fields help consumers and catalogs list and audit presets.

Step 2—create the folder structure and the manifest

• Create a folder for the preset. Example:
  my-company-style/
• At the root, create a manifest file named preset.yml and add subfolders for overrides:
  • templates/
  • commands/
  • scripts/
  • README.md

Minimal example preset.yml (place at my-company-style/preset.yml)
name: my-company-style
id: com.example.my-company-style
version: 0.1.0
description: “Company wording, trimmed plan structure, and Spanish localization.”
author:
name: Example Corp
email: infra@example.com
priority: 8
tags:

• style
• localization

Notes about the manifest:

• Spec Kit reads preset.yml to register the preset.
• The important required fields are id, name, and version; add description, author, priority, and tags for usability.
• You can extend the manifest with catalog metadata if you plan to publish.

Step 3—place overrides in the correct locations

• templates/: copy the exact core template filename you want to override (for example, plan-template.md) and edit it. The runtime resolution uses filenames/paths to match.
• commands/: put files that replace command prompt text or companion prompts. For example, speckit.constitution.md or .prompt.md files.
• scripts/: put helper scripts referenced by templates or lifecycle hooks.
• README.md: explain what the preset does, installation implications, and any migration guidance.

Important: keep the same filenames and relative paths used by the core Spec Kit repository (you can inspect core templates in the Spec Kit repo to find correct names). During installation, preset files are copied to .specify/presets// and spec resolution walks the stack automatically, so you don’t manually merge templates.

Example: override the plan template to add a C# code sample

• Create templates/plan-template.md and include a fenced C# block in the example section: …in the template’s code example area include:
  

// Example using our company logging convention 
public class AccountService { private readonly ILogger _log; public AccountService(ILogger log) => _log = log; }

(Templates are plain Markdown — using C# samples inside them is fine.)

Step 4 — local testing during development (fast feedback loop)

• Install your preset into a local project while developing:
  specify preset add –dev /path/to/my-company-style
• Run generation commands that exercise the templates or prompts you modified:
  specify plan –input spec=”Add user login”
• Inspect the generated output to verify your overrides took effect.
• Use Spec Kit helper commands to debug resolution:
  specify preset resolve
  specify artifact (or whichever command your Spec Kit provides to inspect which file “wins”)
• Iterate: change files in your local preset directory and re-run the generation command. The –dev install mode points to your local copy for quick iteration.

Step 5—validate the manifest (quick programmatic check)

• A simple validation ensures required fields are present and helps catch YAML typos. Below is a tiny C# example using YamlDotNet that reads preset.yml and errors if id/name/version are missing.

Commands:

• Add the YamlDotNet package (run in your dotnet project directory):
  dotnet add package YamlDotNet

C# Program (Program.cs):

using System;
using System.IO;
using System.Collections.Generic;
using YamlDotNet.Serialization;
using YamlDotNet.Serialization.NamingConventions;

var yaml = File.ReadAllText("preset.yml");
var deserializer = new DeserializerBuilder()
.WithNamingConvention(CamelCaseNamingConvention.Instance)
.Build();
var preset = deserializer.Deserialize<Dictionary<string, object>>(yaml);

string[] required = new[] { "id", "name", "version" };
foreach (var r in required)
{
  if (!preset.ContainsKey(r))
  {
    Console.Error.WriteLine($"Missing required manifest field: {r}");
    Environment.Exit(2);
  }
}
Console.WriteLine($"Preset OK: {preset["name"]} v{preset["version"]}");

• dotnet run (or dotnet build + dotnet run) in the project containing Program.cs and preset.yml.
• Exit codes: 0 for OK, non-zero for missing required fields. Integrate this into CI to fail fast on manifest mistakes.

Step 6—tests and CI

• Unit or integration tests: create tests that run specify commands in a controlled workspace (temp directory), generate artifacts, and assert expected strings or structural pieces exist.
• Snapshot testing: store small canonical generated files in tests and compare outputs after generation.
• Linting: run your YAML validator and any custom checks (e.g., disallow certain words, ensure semantic versioning).
• CI: run the validation and generation tests for pull requests. If your preset includes scripts, run them in CI to ensure cross-platform behavior or provide both shell and PowerShell variants.

Step 7—package and publish

• Options for sharing:
  • Publish the preset repository on GitHub/GitLab and reference it from a catalog.
  • Host a catalog.json or catalog.yaml listing your preset metadata and URL. Consumers can add presets from catalogs.
  • Use community tooling (e.g., presetify) to generate catalog entries and help with validation/publishing to community catalogs.
• For internal distribution, your team can host the preset repo or a catalog on an internal server and point projects at it.
• Ensure you tag releases using semantic versioning so consumers can pin versions: e.g., v0.1.0.

Step 8—installation and lifecycle for consumers

• Install from a catalog or URL:
  specify preset add
  specify preset add –version
  specify preset add –from
• Install locally for development:
  specify preset add –dev <path/to/preset>
• Remove:
  specify preset remove
• Upgrading a preset is a matter of updating the version and having consumers run an upgrade or specify preset add with a version.

Best practices & warnings

• Keep presets limited to content/formatting/localization. Don’t use presets to implement complex runtime automation.
• Follow semantic versioning. Document changes in README and changelog.
• Prefer small, focused presets over large monolithic presets; it’s easier to compose and upgrade.
• Security: don’t blindly trust third-party catalogs. Inspect preset contents before install and ensure your project policy permits external presets.
• Avoid breaking template API contracts. If you change placeholders or required variables in a template, document the change and bump major version.
• Use meaningful tags in preset.yml so consumers (and catalog tools) can filter presets: tags: [style, spanish, onboarding]
• Provide README.md with examples: “How this preset changes plan-template.md” and sample generated output.
• If you want to supply per-command prompts, include companion .prompt.md files under commands/ with clear naming.

Note: The initial draft of this post was written by BlogWriter and then
edited by Jesse Liberty. Illustrations by Copilot. Caution: LLMs make mistakes; this post is offered as is.

Spec Kit exposes four primitives that solve these problems in a structured, maintainable way:

• Presets fix content and wording (make docs consistent).
• Extensions add behavior and integrations (run code, call Jira/CI).
• Workflows orchestrate multi-step, resumable pipelines (add gates and state).
• Bundles package and version a curated set of the above (one-command onboarding).

This post explains each primitive plainly, shows concrete manifests and examples (CLI + Visual Studio Code), and gives authoring, troubleshooting, and operational guidance so you can pick the right tool for the job.

At-a-glance summary

• Preset — content & prompt overrides (templates/command text). Use to change wording, templates, or organization-wide conventions without changing core code.
• Extension — new capabilities (commands, integrations, hooks). Use to add Jira, git automation, quality gates, or domain-specific behaviors.
• Workflow — a resumable, multi-step YAML pipeline that orchestrates Spec Kit commands, shell steps and human gates.
• Bundle — a versioned, shareable package that installs a curated set of presets, extensions, workflows, and steps together for a team/role.

What they change and when to pick them

• Need different wording, templates, or company style? → Preset.
• Need new integrations, commands, or hooks that run code? → Extension.
• Need to automate a repeatable multi-step process (with gates and state)? → Workflow.
• Need to ship a set of the above to teammates as one installable artifact? → Bundle.

Deep dive: Presets — change what the agent writes
What a preset does

• Presets override templates and prompt text used by Spec Kit’s agent. They are focused on content: wording, section structure, localization, default fields and the text the CLI uses when creating specs/plans/tasks.
• Presets do not (normally) run code, call external services, or change engine behavior.

When to use a preset

• Enforce company style, legal or compliance wording.
• Provide localized templates (Spanish, Japanese).
• Change default structure (one-pager vs full SDD).
• Adjust agent prompt wording for tone/conciseness.

Concrete preset manifest (example)
File path: .specify/presets/company-style.yaml

priority: 10
name: company-style
description: "Company legal & style overrides; Spanish localization for Latin America teams"

templates:
  spec.summary: "Propósito corto (1–2 oraciones)"
  spec.description: |
    Descripción:
    - Objetivo: {{ inputs.goal }}
    - Stakeholders: {{ inputs.stakeholders | join(', ') }}
  spec.security: |
    Consideraciones de seguridad:
    - Autenticación: se requiere 2FA para nuevos endpoints
    - Datos sensibles: cifrado en tránsito y en reposo

How presets stack

• Multiple presets can be active. They stack by numeric priority: lower number = higher precedence. A global company preset (priority 10) can be overridden by a repo-level preset with priority 5.
• When a template ID is present in multiple presets, the lowest-numbered preset wins for that template only.

Authoring and publishing a preset — step-by-step

1. Create a local preset file in .specify/presets/ (YAML or JSON).
2. Test locally by running a generate command that would use the template. Example:
   • CLI: specify plan –input spec=”Add login”
   • Check the generated text for your new wording.
3. If satisfied, publish the preset to your Spec Kit catalog (your org’s registry) so teams can add it with specify preset add company-style@1.0.0.
4. When updates are needed, bump the manifest version and publish a new release. Consumers can upgrade with specify preset update company-style.

VS Code: how to install and test a preset

• Terminal:
  1. Open your workspace in VS Code.
  2. Open integrated terminal (Ctrl+`).
  3. Run: specify preset add company-style
• UI (Spec Kit Companion):
  1. Open the Spec Kit sidebar.
  2. Select Presets → Search → company-style → Install.
  3. Use the “Preview” or “Generate” action in the sidebar to see the template applied.

Troubleshooting common preset issues

• Preset not taking effect: check priorities (lower wins), ensure the preset ID and version installed, and confirm the template ID you modified matches the agent’s template ID (typos happen).
• Conflicting overrides: list installed presets and remove/adjust the one you don’t want (specify preset list; specify preset remove ).

Deep dive: Extensions — add behavior and integrations
What an extension does

• Extensions are plugins that can register new CLI commands, provide templates, offer hooks, and run code. They can call external services (Jira, test runners), enforce checks, or modify repository state (branch creation, commits).
• Use extensions when you need logic beyond textual overrides.

Example extension manifest (minimal)
File: extension.yaml

id: git-jira
version: 0.1.0
name: "Git + Jira integration"
description: "Creates branches, creates Jira tickets, and wires plan acceptance to ticket creation."

commands:
  - id: git.create-branch
    command: specify git branch-for-spec
  - id: jira.create-issue
    command: specify jira create-issue --input summary="{{ inputs.summary }}"

hooks:
  onPlanAccepted: jira.create-issue

permissions:
  network:
    - "jira.example.com"
filesystem:
  read:
    - ".git"
  write:
    - ".git/refs/heads"

Authoring an extension — quick guide

1. Scaffold an extension (your preferred runtime: Node, shell scripts, or compiled binary). Keep it small and well-scoped.
2. Register commands in the manifest and map them to your executable or script.
3. Implement and mock external calls for local testing.
4. Test in a local repo:
   • Install locally: specify extension add ./path/to/extension
   • Run the new command: specify git create-branch –input spec=”…”
5. Publish to catalog once reviewed.

Example behavior: create branch + Jira ticket when a plan is accepted

• Extension registers a hook onPlanAccepted.
• When a workflow step marks the plan accepted, the extension is invoked to create a Jira ticket and a branch.
• Because extensions can run code or call networks, follow security practices (see Security section).

VS Code: installing and using an extension

• Terminal:
  1. Open integrated terminal (Ctrl+`).
  2. Run: specify extension add git-jira
• UI (Spec Kit Companion):
  1. Presets/Extensions view → Search “git-jira” → Install.
  2. The extension’s commands will show up in the Command Palette (Ctrl+Shift+P) under Spec Kit commands; or the companion UI exposes buttons like “Create Jira issue”.

Troubleshooting extensions

• Network permissions denied: check the extension manifest’s network permission and your environment firewall.
• Command missing after install: ensure the extension installed successfully and restart the terminal/VS Code if necessary.

Deep dive: Workflows — orchestrate multi-step, resumable pipelines
What a workflow does

• A workflow is a YAML pipeline that composes agent steps, shell steps, and human gates. Workflows persist run state so you can pause for review and resume later.
• Use workflows to enforce reproducible processes: assess → plan → implement → test → sign-off.

Expanded example workflow (detailed)
File: sdd-pipeline.yml

name: sdd-pipeline
inputs:
  spec:
    type: string
    required: true

steps:
  - id: assess
    type: agent
    command: specify assess --input spec="{{ inputs.spec }}"
    outputs:
      summary: string

  - id: plan
    type: agent
    command: specify plan --input spec="{{ steps.assess.summary }}"
    outputs:
      branch: string
      plan_url: string

  - id: create-branch
    type: shell
    command: |
      git checkout -b "{{ steps.plan.branch }}"
      git push -u origin "{{ steps.plan.branch }}"
    continueOnError: false

  - id: run-tests
    type: shell
    command: |
      ./run-tests.sh --report results.json
    outputs:
      test_report: results.json
    continueOnError: false

  - id: review
    type: gate
    approvers:
      - "team-lead@example.com"
    timeout: "72h"

Key workflow features demonstrated

• Inputs and typed outputs — later steps can reference earlier outputs (templating with {{ }}).
• Mix of agent and shell steps.
• Human gate with approvers and timeout.
• Persisted run state to allow resumption.

Run workflows — CLI and VS Code

• Install catalog workflow:
  specify workflow add sdd-pipeline
• Run from catalog:
  specify workflow run sdd-pipeline –input spec=”Add user authentication”
• Run a local workflow YAML:
  specify workflow run ./sdd-pipeline.yml –input spec=”Add payment flow”

VS Code:

• Terminal: run the same specify workflow commands.
• UI (Spec Kit Companion):
  1. Open Workflows in the sidebar.
  2. Choose a catalog workflow or point to a local YAML.
  3. Click “Start run” and follow the run UI to see step outputs and approve gates.

Authoring a workflow — best practices

• Validate inputs: declare required inputs and types.
• Make steps idempotent where possible (re-running a branch creation should be safe or fail cleanly).
• Persist minimal but useful outputs for later steps (e.g., branch name, plan URL).
• Add clear error handling: use continueOnError judiciously and provide logs for shell steps.
• Test locally by running the workflow with small inputs and stepping through the UI or CLI.

Troubleshooting workflows

• Workflow fails at shell step: open the run’s step logs, reproduce the commands locally in the terminal, fix failing command or environment.
• Gate never approved: ensure approvers are reachable emails and the companion UI sends notifications; approvers can resume runs from VS Code or CLI.

Deep dive: Bundles — package and share a curated stack
What a bundle does

• A bundle is a versioned artifact that declares a set of presets, extensions, workflows, and steps to install together. Bundles don’t create new primitives — they package and pin existing ones so teams get a tested configuration with one command.
• Bundles record provenance of what they installed for clean removal and upgrades.

Example bundle manifest
File: .specify/bundles/backend-team.yaml

id: backend-team
version: 1.0.0
name: "Backend Team Starter"
description: "Preset, extensions, and workflows for backend engineers."

presets:
  - company-style@10
  - backend-layout@5

extensions:
  - git@2.3.0
  - jira@1.1.0

workflows:
  - sdd-pipeline@1.0.0

metadata:
  installedBy: "bundle-maintainer@example.com"
  date: "2026-10-01"

Install / lifecycle commands

• Install a bundle:
  specify bundle install backend-team
  (alias: specify bundle add backend-team)
• List installed bundles:
  specify bundle list
• Upgrade a bundle:
  specify bundle update backend-team –version 1.1.0
• Uninstall/remove a bundle:
  specify bundle remove backend-team

What bundles actually do in a repo

• Install referenced presets, extensions, and workflows into the project.
• Create metadata in .specify/bundles/ to record installed components and pinned versions.
• Allow a single remove command to uninstall everything the bundle introduced.

When to use a bundle

• Onboarding new hires or new projects with a single command.
• Ensuring consistent, pinned tooling across teams.
• Distributing proven configurations for compliance or role-specific setups.

Bundles: VS Code experience

• Terminal:
  1. Open integrated terminal (Ctrl+`).
  2. Run: specify bundle install backend-team
• UI (Spec Kit Companion):
  1. Bundles view → Search → backend-team → Install.
  2. The UI shows progress and created files; it lists the installed components in a panel.

Security, testing, and operational guidance
Vetting extensions

• Treat extensions like any plugin: require code review, run static analysis, and audit network permissions.
• Use least-privilege: only grant network access to specific hosts used by the extension.
• Use CI sandboxing: run untrusted extensions in CI jobs with restricted tokens and ephemeral credentials.

Testing workflows and presets

• Presets: test by generating artifacts locally and comparing before/after outputs. Use a diff tool to confirm only intended changes.
• Workflows: dry-run where possible. Validate inputs and run with small, safe inputs. Test gate behavior by simulating approvals.
• Extensions: unit tests and integration tests against mocked APIs. Provide a local test harness script.

Bundles and provenance

• Always pin versions in bundle manifests to avoid unexpected breaking changes.
• Use bundle metadata to record who installed the bundle and when to enable audits and rollbacks.

Programmatic integration: invoking specify from C#
If you need to call the specify CLI from other tools or CI, capture stdout/stderr. Example (async):

using System.Diagnostics;

var psi = new ProcessStartInfo {
    FileName = "specify",
    Arguments = "workflow run sdd-pipeline --input spec=\"Build login\" --json",
    RedirectStandardOutput = true,
    RedirectStandardError = true,
    UseShellExecute = false,
    CreateNoWindow = true
};

using var proc = Process.Start(psi);
string stdout = await proc.StandardOutput.ReadToEndAsync();
string stderr = await proc.StandardError.ReadToEndAsync();
proc.WaitForExit();
// stdout contains run result (or --json output); stderr contains errors.

In VS Code, run this same program from the integrated terminal or incorporate it into a task that runs on save or during CI.

VS Code practical steps — exact actions users will see

• Open Command Palette (Ctrl+Shift+P). Search “Spec Kit: Install Preset” or “Spec Kit: Run Workflow”.
• Spec Kit Companion sidebar panels:
  • Presets: search, preview, install.
  • Extensions: list, view commands, install.
  • Workflows: catalog view, run, see run state and step logs.
  • Bundles: browse, install, view installed metadata.
• Terminals use standard CLI commands; the UI calls the same CLI under the hood.

Authoring tutorials (concise walkthroughs)
Preset authoring walkthrough (quick)

1. Create file: .specify/presets/company-style.yaml with your overrides.
2. Test: specify plan –input spec=”Add login” and confirm the summary and security sections are replaced.
3. Publish to catalog and instruct teams: specify preset add company-style@1.0.0.

Extension authoring walkthrough (quick)

1. Scaffold a small Node or shell extension and manifest (extension.yaml).
2. Add a command that runs a script to call Jira’s API (use environment tokens).
3. Test by installing locally: specify extension add ./my-extension.
4. Publish after security review.

Workflow authoring walkthrough (quick)

1. Start from sdd-pipeline.yml example above.
2. Run locally: specify workflow run ./sdd-pipeline.yml –input spec=”…”
3. Step through the run in VS Code and fix templating issues.
4. Publish and add to a bundle for distribution.

Bundle authoring walkthrough (quick)

1. Create bundle manifest listing pinned components.
2. Run: specify bundle install ./backend-team.yaml locally to validate the install process.
3. Publish the bundle to the catalog. Team members then run specify bundle install backend-team.

Migration patterns and practical advice

• Start with presets when you only need wording changes (low risk).
• When you find repeating scripts or ad-hoc tools across repos, move them into an extension.
• When a sequence of steps becomes common and should be reproducible, author a workflow.
• When multiple teams need the same combination, wrap all pieces into a bundle.

FAQ / Troubleshooting quick hits

• Preset not applied? Check priority: specify preset list shows installed presets and priority.
• Workflow step failed — how to debug? View step logs in the CLI run output or VS Code run panel; reproduce the shell step locally.
• How do I remove a bundle? specify bundle remove will uninstall components that bundle recorded.
• An extension requires network access — is it safe? Review its permissions in the manifest and audit its code. Use least-privilege credentials.

Glossary

• Preset: content and prompt overrides for templates and text.
• Extension: plugin that adds commands, hooks, and runtime behavior.
• Workflow: a persisted YAML pipeline combining steps, shell commands, and gates.
• Bundle: a versioned package that installs presets, extensions, and workflows together.

Quick CLI reference

• Add preset: specify preset add
• Add extension: specify extension add
• Add workflow from catalog: specify workflow add
• Run workflow: specify workflow run –input spec=”…”
• Run local workflow YAML: specify workflow run ./my-workflow.yml –input spec=”…”
• Install bundle: specify bundle install
• List bundles: specify bundle list

Closing and next steps
Presets, extensions, workflows, and bundles complement each other:

• Presets shape content and tone.
• Extensions implement behavior and integrations.
• Workflows orchestrate repeatable, resumable processes.
• Bundles distribute curated stacks and keep provenance.

Note: The initial draft of this post was written by BlogWriter and then
edited by Jesse Liberty.
Illustrations by Copilot. Caution: LLMs make mistakes; this post is offered as is.

Prompts allow you to manage the exact instructions your chat models receive and let apps pick those instructions at runtime.

That’s the core value of “prompts” in the Model Context Protocol (MCP). MCP prompts let a server publish reusable, argument‑driven prompt templates that clients (including Microsoft Agent Framework agents) can discover, retrieve, and use in LLM chat calls—so behavior, UX, and auditing are consistent across apps.

Key terms (quick definitions)

• MCP server: a service that implements the Model Context Protocol and exposes tools, prompts, and resources to clients.
• Prompt template (MCP “prompt”): a server‑hosted, reusable instruction template that can accept named arguments and return one or more chat messages.
• Prompt arguments: named values (e.g., url, language, timeframe) supplied by the client when calling prompts/get.
• Prompt response messages: the chat messages (roles like system/user/assistant) returned by prompts/get that are ready to be appended to a model call.
• Resource messages: special messages in a prompt response that contain URIs or attachments (files, repo links) the model should consider.

Why MCP prompts matter for developers and product teams

• Central control: product teams can update a prompt template on the server and clients will automatically get the new behavior the next time they fetch it.
• Consistency: multiple agents and apps use the same instructions and checklists (e.g., compliance templates, code‑review checklists).
• Reusability: prompts are parameterized. One server prompt can cover many scenarios by taking arguments.
• Discoverability & UX: prompts/list lets clients surface available commands (slash menus, command palettes) rather than hardcoding instructions into each client.
• Auditability: when agents log which prompt and which arguments were used, teams can trace model behavior back to a server‑controlled template.

How prompts fit into the Microsoft Agent Framework
The Microsoft Agent Framework can connect to MCP servers at runtime. That allows an agent to:

1. Call prompts/list to discover server prompts and show them to the user (for example, as a slash‑command menu).
2. Prompt the user for required arguments (URL, code snippet, language).
3. Call prompts/get (name + arguments) to fetch the populated template as chat messages.
4. Append the returned messages to the chat history and send them to the LLM client (e.g., Azure OpenAI).
   Because the prompt is server‑hosted, the server controls wording, embedded resources, and any instruction to call tools—clients only provide arguments and deliver the resulting messages to the model.

Typical flow (concise)

1. Discover: prompts/list → display options.
2. Select & collect args: user picks a prompt → agent collects required fields.
3. Retrieve: prompts/get(name, args) → server returns promptContent.Messages and optionally resource messages.
4. Use: append returned messages to your chat request and send to the model.

Sample prompts/get JSON (small example)
This is a minimal illustration of what prompts/get might return.
{
“messages”: [
{ “role”: “system”, “content”: “You are an expert summarizer. Focus on key findings and risks.” },
{ “role”: “user”, “content”: “Summarize the document at: https://example.com/report.pdf” }
],
“resources”: [
{ “type”: “uri”, “uri”: “https://example.com/report.pdf“, “description”: “Source PDF” }
]
}

C# examples (illustrative, practical, with error handling)
Notes: the exact MCP SDK namespace and method names vary by SDK version. The examples below follow common patterns used in the MCP quickstart and show how to map MCP messages into a chat client call. Replace transport/creation code with the actual constructors in your MCP SDK.

Install (example)

• Add an MCP client package (example package id: ModelContextProtocol.Client)
• Add your LLM client package (example: Azure.AI.OpenAI)

Example 1 — Summarize document (argument: url)
This example lists prompts, finds summarize-document, calls get with a URL, and sends returned messages to an Azure OpenAI chat client.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using ModelContextProtocol.Client; // example package
using Azure.AI.OpenAI;
using Azure;

async Task SummarizeDocumentAsync(string documentUrl, CancellationToken cancellationToken = default)
{
try
{
// 1) Create MCP client (transport creation is SDK-specific)
var transport = /* create transport per your SDK: HTTP, WebSocket, etc. */;
var mcpClient = await McpClient.CreateAsync(transport, cancellationToken); // 2) List prompts
    var prompts = await mcpClient.ListPromptsAsync(cancellationToken);
    var summarize = prompts.FirstOrDefault(p => p.Name == "summarize-document");
    if (summarize == null)
        throw new InvalidOperationException("Prompt 'summarize-document' not available.");

    // 3) Call prompts/get with required arguments
    var args = new Dictionary<string, object> { ["url"] = documentUrl };
    var promptContent = await summarize.GetAsync(args, cancellationToken);

    // 4) Map MCP messages to OpenAI chat messages
    var openAiClient = new OpenAIClient(new Uri("https://your-azure-endpoint/"), new AzureKeyCredential("AZURE_KEY"));
    var chatOptions = new ChatCompletionsOptions();
    foreach (var m in promptContent.Messages)
    {
        chatOptions.Messages.Add(MapMcpMessageToChatMessage(m));
    }

    // Optional: append follow-up instructions from the user
    chatOptions.Messages.Add(new ChatMessage(ChatRole.User, "Please keep the summary under 200 words."));

    var response = await openAiClient.GetChatCompletionsAsync("deployment-name", chatOptions, cancellationToken);
    Console.WriteLine(response.Value.Choices[0].Message.Content);
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
    Console.Error.WriteLine("Prompt not found: " + ex.Message);
}
catch (Exception ex)
{
    Console.Error.WriteLine("Error fetching prompt or calling model: " + ex.Message);
    throw;
}}

static ChatMessage MapMcpMessageToChatMessage(McpMessage m)
{
var role = m.Role switch
{
  system" => ChatRole.System,
  "assistant" => ChatRole.Assistant,
  _ => ChatRole.User
};
  return new ChatMessage(role, m.Content);
}

Example 2 — Code review (arguments: code, optional language)
This example demonstrates sending a code snippet and language argument to a code_review prompt. The server might return a checklist system message plus resource URIs pointing to related files.

async Task CodeReviewAsync(string codeSnippet, string language = "csharp", CancellationToken cancellationToken = default)
{
var transport = /* create transport */;
var mcpClient = await McpClient.CreateAsync(transport, cancellationToken);
var prompts = await mcpClient.ListPromptsAsync(cancellationToken);
var codePrompt = prompts.FirstOrDefault(p => p.Name == "code_review");
if (codePrompt == null) throw new InvalidOperationException("code_review not available");

var args = new Dictionary<string, object> { ["code"] = codeSnippet, ["language"] = language };
var promptContent = await codePrompt.GetAsync(args, cancellationToken);

var openAiClient = new OpenAIClient(new Uri("https://your-azure-endpoint/"), new AzureKeyCredential("KEY"));
var chatOptions = new ChatCompletionsOptions();
foreach (var m in promptContent.Messages)
{
    chatOptions.Messages.Add(MapMcpMessageToChatMessage(m));
}

var response = await openAiClient.GetChatCompletionsAsync("deployment-name", chatOptions, cancellationToken);
Console.WriteLine(response.Value.Choices[0].Message.Content);
}

Practical tips (concrete, actionable)

• Validate arguments on the client: whitelist allowed languages, enforce URL schemes (https), and check length limits. Refuse or sanitize inputs that look like secrets.
• Prefer proxying or previewing third‑party resources instead of sending raw URIs to external servers. If you must share URIs, use signed, time‑limited links.
• Handle common error codes: 404 = prompt not found, 400 = missing/invalid args, 429 = rate limit; implement exponential backoff and circuit breakers.
• Cache prompt metadata: calls to prompts/list are relatively cheap but cache names/descriptions and refresh periodically to avoid UI delays.
• UI recommendations: present prompts in a command palette or slash‑menu; show required arguments and a small template preview before fetching; allow an editable preview so users can tweak arguments before sending.
• Embedded resources: if the prompt returns resource messages, decide whether to fetch the resource text (and include it in the chat) or attach a link. If fetching, enforce size limits and sanitize content.
• Versioning & breaking changes: because prompts are server‑controlled, add an ability to pin a prompt version (if the server supports it) or keep integration tests that validate prompt behavior after server updates.
• Audit and tracing: log prompt name + non‑sensitive args and add trace IDs/headers when calling MCP servers so you can correlate user actions and prompt outputs for debugging and compliance.

Security & operational specifics

• Redact secrets: never send API keys, passwords, or PII to a third‑party MCP server. Run argument sanitization and redaction on the client.
• Signed URLs: use expiring signed URLs when providing attachments to external servers; this limits exposure.
• Policy & approval: treat server‑hosted prompts as part of your product’s compliance surface. Establish a governance process for who can change server prompts.
• Headers & audit: follow the Agent Framework guidance for adding audit headers and tracing to MCP calls. Store logs of prompt usage (prompt name, timestamp, actor) with care for privacy.

Error handling & retries (short patterns)

• Use CancellationToken for timeouts.
• Retry transient errors (HTTP 5xx, 429) with an exponential backoff and jitter.
• Surface user‑friendly messages for 400/422 responses (missing args or invalid input) and guide the user to correct inputs.

Where to read next

• Model Context Protocol prompts spec: modelcontextprotocol.io (prompts/list and prompts/get shapes).
• Microsoft Agent Framework docs: on integrating MCP prompts and security guidance.
• .NET quickstart and MCP C# SDK samples: for precise types and SDK usage in production.

An agent in the Microsoft Agent Framework (MAF) talks to an LLM whenever it needs to:
(1) decide what to do or generate text (initial planning/response generation),
(2) decide whether to call a tool and provide its arguments (function/tool calling), and
(3) incorporate tool outputs and continue reasoning or synthesize the final reply.

A single agent run commonly produces multiple model calls in a loop: planning → tool call(s) → synthesis → (repeat if needed).

MAF implements a layered agent pipeline. Calling agent.RunAsync (or equivalent) starts a run that flows down middleware and context providers before ever hitting a model client (the LLM), and the run’s responses flow back up. That orchestration is why an agent doesn’t “just call the LLM once” by default—the framework determines when and how many model requests are required based on the agent’s instructions, tools, and middleware.

Three middleware layers you can hook in

• Agent-run middleware: wraps the entire run (fires once per run). Good for run-level telemetry or cancellation.
• Function/tool middleware: wraps each tool invocation (fires for each tool call). Useful for gating tool execution, approvals, or stubbing tools for tests.
• Chat / IChatClient middleware: wraps every underlying model/chat client call (fires every time the framework calls the model). Useful for logging prompts, redaction, or cost measurement.

Typical sequence that triggers LLM calls

1. Request received → pipeline and context providers populate run context (no model call yet).
2. Initial reasoning/plan → LLM call to decide plan (generate response or choose a tool). This is typically the first chat call.
3. If the model chooses a tool → framework executes function middleware and runs the tool (tool execution itself may be non-LLM code).
4. After tool returns → agent calls LLM again to integrate tool output and produce/synthesize the final response.
5. If needed, the LLM may ask to call another tool and the loop continues. Each cycle can add one (or more, depending on provider semantics) model calls.

C# examples

1. Minimal agent run (RunAsync typically triggers at least one LLM call)
   This follows the quick-start pattern; RunAsync goes through the pipeline and will call the model as needed.

using System;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

var agent = new AIProjectClient(
new Uri("https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"),
new AzureCliCredential()
).AsAIAgent(
model: "gpt-5.4-mini",
instructions: "You are a helpful assistant. Keep answers brief."
);

var result = await agent.RunAsync("What is the largest city in France?");
Console.WriteLine(result);

2. Tool/function call flow (model decides to call a tool → tool executes → model synthesizes)
   Sketch of registering a tool; the run will typically perform model → tool → model:

// sketch
var myTool = new FunctionTool(
name: "get-weather",
description: "Get weather for a city",
handler: async (args) => {
return await GetWeatherAsync(args); // actual non-LLM work
}
);

var agent = new ChatClientAgentBuilder()
.UseModel("gpt-5.x")
.RegisterTool(myTool)
.Build();

// This RunAsync will likely:
// 1) call model to decide plan (may return "call get-weather")
// 2) execute myTool (no LLM)
// 3) call model to synthesize the final reply
var response = await agent.RunAsync("What's the weather in Seattle tomorrow?");
Console.WriteLine(response);

3. Chat middleware: intercept every LLM call (log each model invocation)
   Chat-level middleware runs on every model/chat client request:

async Task LoggingChatMiddleware(
IEnumerable messages,
ChatOptions? options,
IChatClient innerClient,
CancellationToken cancellationToken)
{
  Console.WriteLine($"[ChatMiddleware] Sending {messages.Count()} messages to model...");
  var resp = await innerClient.GetResponseAsync(messages, options, cancellationToken);
  Console.WriteLine($"[ChatMiddleware] Model returned {resp.Messages.Count} messages.");
  return resp;
}

// Register this middleware when configuring IChatClient / ChatClientAgent (see docs for exact APIs).

4. Agent-run and function middleware (brief sketches)

• Agent-run middleware: wrap whole run for telemetry or per-run constraints.
• Function middleware: intercept each tool invocation (e.g., require approval):

// Function middleware sketch
async Task ApproveThenExecuteMiddleware(
ToolInvocation invocation,
Func<ToolInvocation, Task> next,
CancellationToken ct)
{
  if (!IsApproved(invocation)) throw new Exception("Tool call not approved.");
    return await next(invocation); // proceed to actual tool handler
}

Practical caveats and best practices

• Multiple LLM calls per run are normal. Instrument chat middleware to measure API usage and cost.
• Tool execution is non-LLM work; function middleware can gate, mock, or log tool runs.
• Providers differ: function-calling semantics, streaming behavior, and limits can change how often or how responses are streamed.
• Use concise instructions and tool schemas so the model makes fewer unnecessary tool calls.
• If you need strict accounting of model usage, intercept at chat middleware (every model call passes there).