<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Abderrahmane Nait Brahim</title>
    <description>The latest articles on DEV Community by Abderrahmane Nait Brahim (@abdounb).</description>
    <link>https://dev.to/abdounb</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4194193%2Fe29a471e-304d-4477-8c66-3fcbd90eed6e.jpg</url>
      <title>DEV Community: Abderrahmane Nait Brahim</title>
      <link>https://dev.to/abdounb</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/abdounb"/>
    <language>en</language>
    <item>
      <title>Your AI Coding Agent Has Amnesia—Here's the Patch</title>
      <dc:creator>Abderrahmane Nait Brahim</dc:creator>
      <pubDate>Tue, 20 Oct 2026 00:57:00 +0000</pubDate>
      <link>https://dev.to/abdounb/your-ai-coding-agent-has-amnesia-heres-the-patch-38cg</link>
      <guid>https://dev.to/abdounb/your-ai-coding-agent-has-amnesia-heres-the-patch-38cg</guid>
      <description>&lt;p&gt;A single browser snapshot can cost your AI coding agent 56 KB of context. Twenty GitHub issues can consume another 59 KB. The agent hasn't written a line of code, yet its working memory is already filling with raw data.&lt;/p&gt;

&lt;p&gt;Then comes compaction: the conversation is compressed to make room, and important details about earlier decisions or unfinished work can get lost.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Context Mode&lt;/strong&gt; tackles both problems. The source-available MCP server recently reached #1 on GitHub Trending on October 17, 2026, and its repository now shows roughly 30,900 stars. Its premise is simple: stop feeding the model everything, and give it a way to retrieve what matters. &lt;a href="https://github.com/mksglu/context-mode" rel="noopener noreferrer"&gt;Project repository&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Four ways agents waste context
&lt;/h2&gt;

&lt;p&gt;Context Mode identifies four related problems:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Raw tool output.&lt;/strong&gt; Browser snapshots, logs, API responses, and file reads can fill the context window with data the model doesn't need to see in full.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Lost working memory.&lt;/strong&gt; When a conversation compacts, important details about the task and previous actions can disappear from the active context.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Verbose responses.&lt;/strong&gt; Models can spend output tokens on filler and repetition. Context Mode explicitly doesn't try to control this.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The wrong kind of work.&lt;/strong&gt; Models often read large amounts of data to perform simple calculations that a short script could handle.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The first two are the main targets. The third is an explicit non-goal, while the fourth motivates the project's most interesting technique: &lt;strong&gt;think in code&lt;/strong&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Think in code, not tool calls
&lt;/h2&gt;

&lt;p&gt;Suppose you want to count lines in every TypeScript file under &lt;code&gt;src/&lt;/code&gt;. A typical agent might repeatedly read files and count their contents. The raw source consumes context even though the final answer is only a list of filenames and numbers.&lt;/p&gt;

&lt;p&gt;Context Mode offers &lt;code&gt;ctx_execute&lt;/code&gt;, which runs code in a separate process and returns its standard output to the model. Instead of reading every file into the conversation, the agent can calculate the answer locally:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="nf"&gt;ctx_execute&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;javascript&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;`
  const files = fs.readdirSync('src').filter(f =&amp;gt; f.endsWith('.ts'));
  files.forEach(f =&amp;gt;
    console.log(
      f + ': ' +
      fs.readFileSync('src/' + f, 'utf8').split('&lt;/span&gt;&lt;span class="se"&gt;\\&lt;/span&gt;&lt;span class="s2"&gt;n').length +
      ' lines'
    )
  );
`&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The result is a compact list instead of the full contents of every file.&lt;/p&gt;

&lt;p&gt;The project's README gives a larger example: &lt;strong&gt;47 file-reading calls consuming 700 KB become one &lt;code&gt;ctx_execute&lt;/code&gt; call returning 3.6 KB&lt;/strong&gt;. Its benchmark table also reports reducing a 56.2 KB Playwright snapshot to 299 bytes. These are project-reported results, not guarantees for every repository or task.&lt;/p&gt;

&lt;p&gt;Context Mode supports 12 execution runtimes, including JavaScript, TypeScript, Python, Shell, Go, Rust, and Ruby. The important idea isn't the language count; it's separating computation from the information the model needs to reason about.&lt;/p&gt;

&lt;h2&gt;
  
  
  Memory that survives compaction
&lt;/h2&gt;

&lt;p&gt;Context Mode also maintains session information in SQLite, using FTS5 full-text search and BM25 ranking to retrieve relevant records.&lt;/p&gt;

&lt;p&gt;Rather than stuffing an entire conversation back into the context window, it can record events from a coding session and retrieve relevant information later. Its hooks support this process around compaction and session startup: a snapshot helps preserve working state, and the next session can restore relevant context.&lt;/p&gt;

&lt;p&gt;This isn't an unlimited memory or a guarantee that the model will never forget something. Retrieval depends on what was recorded and what can be found. But it offers an alternative to repeatedly injecting large amounts of history into every prompt.&lt;/p&gt;

&lt;p&gt;The project supports 17 coding-agent platforms through different combinations of MCP integration, hooks, and plugins. Not every platform receives identical functionality.&lt;/p&gt;

&lt;h2&gt;
  
  
  Try it in about a minute
&lt;/h2&gt;

&lt;p&gt;The simplest complete setup is the Claude Code plugin. Check that Claude Code is installed and that your version meets the project's stated minimum:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;claude &lt;span class="nt"&gt;--version&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Inside Claude Code, install the plugin:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Restart Claude Code, or run &lt;code&gt;/reload-plugins&lt;/code&gt; if available.&lt;/p&gt;

&lt;p&gt;Then run the diagnostic:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;/context-mode:ctx-doctor
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The doctor checks the installation, execution runtimes, hooks, and SQLite/FTS5 support. Resolve any reported failures before assuming automatic routing works.&lt;/p&gt;

&lt;p&gt;To inspect the savings during a coding session, run:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;/context-mode:ctx-stats
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;You'll get usage and context-saving statistics for the current session.&lt;/p&gt;

&lt;p&gt;Prefer a smaller trial? You can register the MCP server directly from your terminal:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;claude mcp add context-mode &lt;span class="nt"&gt;--&lt;/span&gt; npx &lt;span class="nt"&gt;-y&lt;/span&gt; context-mode
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This provides the MCP tools without the full plugin's automatic routing hooks. The agent can use the tools, but it won't receive the same automatic guidance to route large outputs through them. See the &lt;a href="https://github.com/mksglu/context-mode#install" rel="noopener noreferrer"&gt;installation instructions&lt;/a&gt; for the current platform-specific setup.&lt;/p&gt;

&lt;h2&gt;
  
  
  What it fixes—and what it doesn't
&lt;/h2&gt;

&lt;p&gt;Context Mode's appeal is that it tackles a practical constraint in agentic coding: tool results can consume far more context than the useful answer they contain. Its sandboxed execution, searchable session history, and routing hooks attempt to keep that overhead under control.&lt;/p&gt;

&lt;p&gt;There are caveats. Context savings depend on the workload and how consistently an agent uses the provided tools. A short output can still be wrong, and a small result doesn't guarantee that the model retained the right information. Review the actual output and measure your own sessions instead of assuming the README's benchmark applies to your project.&lt;/p&gt;

&lt;p&gt;The word &lt;em&gt;sandbox&lt;/em&gt; also deserves care: a separate process isn't automatically a hardened security boundary. Don't execute untrusted code just because the project calls its execution environment a sandbox, and don't send sensitive information into the model's context unnecessarily.&lt;/p&gt;

&lt;p&gt;Finally, Context Mode doesn't dictate how concise or verbose the model's answers should be. It changes where data is processed and retrieved, not the writing style of the final response.&lt;/p&gt;

&lt;p&gt;That distinction is the interesting part. Making context windows larger is one response to agent amnesia. Making agents more selective about what enters those windows is another—and Context Mode is a practical implementation worth testing.&lt;/p&gt;

</description>
    </item>
    <item>
      <title>Your AI Agent Has Been Thinking Out Loud This Whole Time</title>
      <dc:creator>Abderrahmane Nait Brahim</dc:creator>
      <pubDate>Mon, 19 Oct 2026 23:02:00 +0000</pubDate>
      <link>https://dev.to/abdounb/your-ai-agent-has-been-thinking-out-loud-this-whole-time-2f2d</link>
      <guid>https://dev.to/abdounb/your-ai-agent-has-been-thinking-out-loud-this-whole-time-2f2d</guid>
      <description>&lt;p&gt;Watch an AI agent "think" and you'll notice something wasteful: it writes out every intermediate thought in full English sentences, token by token, before it ever gets to the part that matters — calling a tool, running code, giving you an answer. That's not reasoning. That's narrating.&lt;/p&gt;

&lt;p&gt;A paper and open-source release from Stanford, UIUC, and Together AI — dropped days ago, front-paged on Hacker News yesterday — argues the narration was never necessary. It's called &lt;strong&gt;HybridAgent&lt;/strong&gt;, and the pitch is almost rude in its simplicity: let the model think in raw vectors instead of words, and only switch to text when something outside the model actually needs to read it.&lt;/p&gt;

&lt;h2&gt;
  
  
  The trick: two modes, one generation
&lt;/h2&gt;

&lt;p&gt;Most "efficient reasoning" research picks a side — either the model reasons in latent space (fast, but opaque and bad at using tools) or it reasons in text (slow, token-hungry, but legible). HybridAgent refuses to pick. It moves between both &lt;em&gt;within a single generation pass&lt;/em&gt;, using a small adapter called &lt;strong&gt;HybridLink&lt;/strong&gt; that maps the model's last hidden state straight back into its own input-embedding space. That sidesteps the usual bottleneck — decode a token, re-embed it, feed it back in — and lets the model keep "thinking" in pure vector form for dozens of steps before it ever has to commit to a word.&lt;/p&gt;

&lt;p&gt;Two special tokens, &lt;code&gt;&amp;lt;latent&amp;gt;&lt;/code&gt; and &lt;code&gt;&amp;lt;/latent&amp;gt;&lt;/code&gt;, mark the on-ramp and off-ramp. Outside those tags, it's a normal language model making tool calls, reading search results, writing an answer. Inside them, it's compressing an entire chain of thought into something closer to a held breath than a sentence.&lt;/p&gt;

&lt;p&gt;The part that should make skeptics less nervous: none of this is a black box by default. An "interpretable latent mode" renders every latent step back out as pseudo-text, so you can literally watch a HybridAgent's internal monologue as an HTML report — garbled, abbreviated, but legible. In one released trace, a span of 42 latent steps decodes to something like &lt;em&gt;"the the speed of speed in air at 20° is about 343... should verify... let me search"&lt;/em&gt; — recognizably the ghost of a real thought, not noise.&lt;/p&gt;

&lt;h2&gt;
  
  
  How it learned to switch
&lt;/h2&gt;

&lt;p&gt;Training is two stages. First, HybridSFT teaches the base model (built on Qwen3, at 8B and 14B) to coordinate with HybridLink at all — basic fluency in switching modes. Then HybridRL takes over and learns &lt;em&gt;when&lt;/em&gt; latent mode is worth it, rewarded on correctness, output format, and whether tool calls actually succeed. The model isn't told to minimize tokens; it discovers that thinking quietly is often cheaper and just as accurate.&lt;/p&gt;

&lt;h2&gt;
  
  
  The numbers
&lt;/h2&gt;

&lt;p&gt;Across 11 benchmarks spanning math, science, medicine, search, and agentic tasks, at three model scales, HybridAgent beats frontier text-based and latent-only agents by 10.4% on average — while cutting token usage 35.5–54.7%, running 1.8–2.6x faster, and costing 2.7–3.7x less. An ablation check matters more than the headline stats: swap a model's latent spans with ones from unrelated problems, and accuracy drops 45–51%. The latent thinking isn't filler — it's doing real work. Meanwhile tool-call execution stays reliable at 99.7%, so the efficiency gains aren't coming at the cost of the part that actually touches the outside world.&lt;/p&gt;

&lt;h2&gt;
  
  
  Try it
&lt;/h2&gt;

&lt;p&gt;Everything's on GitHub (&lt;code&gt;togethercomputer/HybridAgent&lt;/code&gt;, MIT-licensed) with runnable checkpoints, not just a paper:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;git clone https://github.com/togethercomputer/HybridAgent.git &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;cd &lt;/span&gt;HybridAgent
pip &lt;span class="nb"&gt;install&lt;/span&gt; &lt;span class="nt"&gt;-r&lt;/span&gt; requirements.txt &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; pip &lt;span class="nb"&gt;install&lt;/span&gt; &lt;span class="nt"&gt;-e&lt;/span&gt; &lt;span class="nb"&gt;.&lt;/span&gt;
&lt;span class="nb"&gt;cp&lt;/span&gt; .env.example .env   &lt;span class="c"&gt;# add a TAVILY_API_KEY for the search tool&lt;/span&gt;
python &lt;span class="nt"&gt;-m&lt;/span&gt; hybrid_inference.run_batch &lt;span class="nt"&gt;--model&lt;/span&gt; togethercomputer/HybridAgent-8B-Agentic
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;You'll need a CUDA GPU; the Qwen3 tokenizer already ships with the anchor tokens baked in.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where this sits
&lt;/h2&gt;

&lt;p&gt;It's not alone — LatentMAS, from a separate group, applies a similar idea to multi-agent systems, passing latent thoughts between agents instead of within one. HybridAgent's distinction is that it's single-agent, fully inspectable, and already shipping usable weights rather than just a method description. That's probably why it's the one getting the HN traction right now: it's something you can &lt;code&gt;git clone&lt;/code&gt; on a Tuesday night, not something you have to reimplement from a methods section.&lt;/p&gt;

&lt;p&gt;The headline isn't that agents got smarter. It's that they finally stopped assuming "smarter" has to mean "more words." For anyone running agent pipelines at any real scale, that's the metric that was quietly bankrupting them the whole time.&lt;/p&gt;

</description>
      <category>tooling</category>
      <category>ai</category>
      <category>agents</category>
    </item>
    <item>
      <title>Build an AI Architecture Decision Gate for GitHub Pull Requests</title>
      <dc:creator>Abderrahmane Nait Brahim</dc:creator>
      <pubDate>Mon, 19 Oct 2026 13:15:07 +0000</pubDate>
      <link>https://dev.to/abdounb/build-an-ai-architecture-decision-gate-for-github-pull-requests-28a5</link>
      <guid>https://dev.to/abdounb/build-an-ai-architecture-decision-gate-for-github-pull-requests-28a5</guid>
      <description>&lt;p&gt;Code explains changes, but it doesn't often explain why.&lt;/p&gt;

&lt;p&gt;A developer might introduce a cache, switch databases, or change a service boundary. The implementation lands, but the reasoning behind it exists only in a pull-request discussion, or nowhere at all. Months later, someone else has to reconstruct the decision from the code.&lt;/p&gt;

&lt;p&gt;Architecture Decision Records (ADRs) solve this by documenting a decision's context, alternatives, and consequences. The trouble is it's tempting to postpone writing them.&lt;/p&gt;

&lt;p&gt;On October 15, 2026, GitHub Agentic Workflows highlighted a Design Decision Gate that inspects pull requests, checks for existing ADRs, and drafts one when needed. Let's build a smaller version using GitHub Agentic Workflows, GitHub's framework for repository automation powered by AI agents.&lt;/p&gt;

&lt;h2&gt;
  
  
  1. Set up GitHub Agentic Workflows
&lt;/h2&gt;

&lt;p&gt;You'll need a GitHub repository with Actions enabled, the GitHub CLI, and access to a supported AI engine. This example uses GitHub Copilot; other engines require their corresponding authentication setup.&lt;/p&gt;

&lt;p&gt;Install the Agentic Workflows extension and authenticate your GitHub CLI account:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;gh auth login &lt;span class="nt"&gt;--scopes&lt;/span&gt; repo,workflow
gh extension &lt;span class="nb"&gt;install &lt;/span&gt;github/gh-aw
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;GitHub Agentic Workflows are in public preview, so syntax and capabilities may change. Check the current quickstart before following the setup process.&lt;/p&gt;

&lt;p&gt;Create a repository label named &lt;code&gt;implementation&lt;/code&gt;. We'll use it to decide which pull requests require analysis, instead of spending tokens on every documentation touch-up.&lt;/p&gt;

&lt;h2&gt;
  
  
  2. Define the workflow
&lt;/h2&gt;

&lt;p&gt;Create a workflow source file in the repository's GitHub workflows directory, for example &lt;code&gt;.github/workflows/adr-gate.md&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="nn"&gt;---&lt;/span&gt;
&lt;span class="na"&gt;description&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;Propose&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;ADRs&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;for&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;significant&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;pull&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;requests"&lt;/span&gt;
&lt;span class="na"&gt;on&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;pull_request&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;types&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;[&lt;/span&gt;&lt;span class="nv"&gt;labeled&lt;/span&gt;&lt;span class="pi"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;ready_for_review&lt;/span&gt;&lt;span class="pi"&gt;]&lt;/span&gt;
    &lt;span class="na"&gt;names&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;implementation"&lt;/span&gt;&lt;span class="pi"&gt;]&lt;/span&gt;
&lt;span class="na"&gt;permissions&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;contents&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;read&lt;/span&gt;
  &lt;span class="na"&gt;pull-requests&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;read&lt;/span&gt;
  &lt;span class="na"&gt;copilot-requests&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;write&lt;/span&gt;
&lt;span class="na"&gt;engine&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;copilot&lt;/span&gt;
&lt;span class="na"&gt;tools&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;github&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;mode&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;gh-proxy&lt;/span&gt;
    &lt;span class="na"&gt;toolsets&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;[&lt;/span&gt;&lt;span class="nv"&gt;default&lt;/span&gt;&lt;span class="pi"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;repos&lt;/span&gt;&lt;span class="pi"&gt;]&lt;/span&gt;
&lt;span class="na"&gt;safe-outputs&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;add-comment&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;max&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="m"&gt;1&lt;/span&gt;
  &lt;span class="na"&gt;push-to-pull-request-branch&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;allowed-files&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="s"&gt;docs/adr/**&lt;/span&gt;
  &lt;span class="na"&gt;noop&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
&lt;span class="na"&gt;timeout-minutes&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="m"&gt;15&lt;/span&gt;
&lt;span class="nn"&gt;---&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Its configuration specifies the pull-request events to monitor, the AI engine, the permissions required, and the permitted write actions. The crucial safety setting is a restriction on generated changes: even when the agent is authorized to propose a change, its branch-write operation is limited to the ADR directory. The agent job itself has read-only repository permissions; configured safe outputs handle permitted writes separately.&lt;/p&gt;

&lt;p&gt;For personal repositories, Copilot authentication may require a &lt;code&gt;COPILOT_GITHUB_TOKEN&lt;/code&gt; secret. Follow the authentication guide for your chosen engine.&lt;/p&gt;

&lt;h2&gt;
  
  
  3. Give the agent a narrow job
&lt;/h2&gt;

&lt;p&gt;The agent's instructions should define a single responsibility: determine whether a pull request introduces a significant architectural decision that needs documenting.&lt;/p&gt;

&lt;p&gt;It should read the pull-request description, inspect changed files, and search existing ADRs for a record covering the decision. If the change is routine, it should explain why no ADR is necessary. If an existing ADR already covers the change, it should report whether the implementation aligns with that decision.&lt;/p&gt;

&lt;p&gt;When a significant decision lacks documentation, the agent should draft an ADR with four sections: context, decision, alternatives considered, and consequences.&lt;/p&gt;

&lt;p&gt;Every claim must be grounded in the pull request or existing repository evidence. If the rationale or alternatives cannot be inferred, the agent should explicitly say so instead of inventing the author's reasoning.&lt;/p&gt;

&lt;p&gt;The workflow should propose the draft in the designated ADR directory and leave a concise pull-request comment explaining what requires review.&lt;/p&gt;

&lt;p&gt;Append the following instructions beneath the closing &lt;code&gt;---&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;&lt;span class="gh"&gt;# Architecture Decision Gate&lt;/span&gt;

Inspect the triggering pull request and determine whether it
introduces a significant architectural decision.

&lt;span class="gu"&gt;## Procedure&lt;/span&gt;
&lt;span class="p"&gt;
1.&lt;/span&gt; Read the pull-request description, changed files, and diff.
&lt;span class="p"&gt;2.&lt;/span&gt; Search &lt;span class="sb"&gt;`docs/adr/`&lt;/span&gt; for an existing decision that covers the change.
&lt;span class="p"&gt;3.&lt;/span&gt; If the change is routine or no architectural decision is evident,
   use &lt;span class="sb"&gt;`noop`&lt;/span&gt; and briefly explain why.
&lt;span class="p"&gt;4.&lt;/span&gt; If an existing ADR covers the change, compare its decision with
   the implementation and report alignment or specific divergences.
&lt;span class="p"&gt;5.&lt;/span&gt; If a significant decision lacks an ADR, draft one using:
&lt;span class="p"&gt;   -&lt;/span&gt; Context
&lt;span class="p"&gt;   -&lt;/span&gt; Decision
&lt;span class="p"&gt;   -&lt;/span&gt; Alternatives Considered
&lt;span class="p"&gt;   -&lt;/span&gt; Consequences

Base every claim on the pull request or existing repository evidence.
Write "Not inferable from current PR evidence" where information
is missing. Never invent the author's rationale or alternatives.

If a draft is justified, write it under &lt;span class="sb"&gt;`docs/adr/`&lt;/span&gt; using a
filename based on the pull-request number and a short title.
Use the configured branch-write safe output to propose the draft,
then use the comment safe output to explain what requires review.

Keep the comment concise and provide one clear next action.
If nothing requires action, use &lt;span class="sb"&gt;`noop`&lt;/span&gt;.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is deliberately smaller than GitHub's own example, which includes additional handling for labels, linked issues, large diffs, configurable directories, and reporting templates. Consult the original workflow when you need those features.&lt;/p&gt;

&lt;h2&gt;
  
  
  4. Compile and review it
&lt;/h2&gt;

&lt;p&gt;Compile and validate the workflow using the Agentic Workflows CLI:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;gh aw compile
gh aw validate
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Review the generated &lt;code&gt;.github/workflows/adr-gate.lock.yml&lt;/code&gt; alongside the Markdown source, then commit both files to the repository:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;git add .github/workflows/adr-gate.md &lt;span class="se"&gt;\&lt;/span&gt;
  .github/workflows/adr-gate.lock.yml
git commit &lt;span class="nt"&gt;-m&lt;/span&gt; &lt;span class="s2"&gt;"Add AI architecture decision workflow"&lt;/span&gt;
git push
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Do not treat successful compilation as proof that the agent behaves correctly. Compilation checks the workflow definition; runtime behavior still needs testing.&lt;/p&gt;

&lt;h2&gt;
  
  
  5. Test two contrasting pull requests
&lt;/h2&gt;

&lt;p&gt;Use a test repository before enabling this workflow on a production codebase.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Test A: routine change.&lt;/strong&gt; Open a pull request that only corrects a typo. Add the &lt;code&gt;implementation&lt;/code&gt; label to trigger analysis. The agent should explain why no ADR is needed and take no further action.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Test B: architectural change.&lt;/strong&gt; Open a pull request that introduces a new database or changes a service boundary, without documenting the rationale. The agent should either draft an ADR grounded in the available evidence or identify what information is missing.&lt;/p&gt;

&lt;p&gt;Inspect the Actions logs, comments, and any generated file. Confirm that writes stay within the designated ADR directory and that unsupported or ambiguous cases are handled safely. Do not claim success until both scenarios have actually run.&lt;/p&gt;

&lt;h2&gt;
  
  
  6. Treat it as a reviewer, not an architect
&lt;/h2&gt;

&lt;p&gt;An ADR generated from a diff is still a hypothesis about the author's intent. A patch can show that a database changed; it usually cannot explain every alternative the team considered or every operational constraint.&lt;/p&gt;

&lt;p&gt;The workflow should therefore create a starting point for review, not silently turn plausible guesses into institutional knowledge. Pull-request diffs are untrusted input, too: keep permissions minimal and inspect the generated workflow before enabling it.&lt;/p&gt;

&lt;p&gt;This prototype comments on decisions and proposes documentation. It does &lt;strong&gt;not&lt;/strong&gt; guarantee that a pull request cannot merge without an ADR. To enforce that policy, add and test an explicit required-check or branch-protection mechanism; a comment alone is not a merge gate.&lt;/p&gt;

&lt;p&gt;The payoff is simple: significant design decisions get documented while their context is fresh, without asking engineers to start every ADR from a blank page. The agent handles the first draft. The humans remain responsible for the decision.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>agentskills</category>
    </item>
  </channel>
</rss>
