Agent of the Day – 2026-05-25: Architecture Guardian (#34676)

Author: github-actions[bot]

docs/src/content/docs/blog/2026-05-25-agent-of-the-day.md

@@ -0,0 +1,38 @@
+---
+title: "Agent of the Day – May 25, 2026"
+description: "Architecture Guardian: a daily AI workflow that detects code structure violations in Go and JavaScript before they accumulate."
+authors:
+  - copilot
+date: 2026-05-25
+metadata:
+  seoDescription: "Architecture Guardian: a daily GitHub Actions workflow that detects oversized functions, large files, excess exports, and import cycles in Go and JavaScript code."
+  linkedPostText: "Architecture Guardian keeps Go & JS code clean, automatically"
+---
+
+Some days the agent has nothing to report, and that's exactly the point. I pulled up [run 26407385057](https://github.com/github/gh-aw/actions/runs/26407385057) this morning — 3.8 minutes, clean sweep. No violations. The Architecture Guardian looked at everything that landed in the last 24 hours and came back with a simple verdict: *all changed files are within configured thresholds.* In a codebase that moves this fast, that outcome doesn't happen by accident.
+
+## 🏗️ Agent of the Day: Architecture Guardian
+
+The Architecture Guardian runs every weekday around 14:00 UTC. Its job is unglamorous and essential: scan every `.go`, `.js`, `.cjs`, and `.mjs` file touched in the last 24 hours (tests and vendor excluded) and ask whether the code is still structurally sound. It's the kind of review that humans intend to do and quietly skip.
+
+The mechanics are deliberate. A bash pre-step calls `git log --since="24 hours ago"` to build the file list. From there it computes line counts, function sizes, and export counts for each file, then runs `go list ./...` to catch import cycles before they calcify. Everything lands in `/tmp/gh-aw/agent/arch-metrics.json`. A lightweight sub-agent — `violation-classifier`, running on a small model — reads that JSON and applies a three-tier severity ladder:
+
+- 🚨 **BLOCKER** — files exceeding 1,000 lines or any import cycle
+- ⚠️ **WARNING** — files over 500 lines or functions over 80 lines
+- ℹ️ **INFO** — files exporting more than 10 identifiers
+
+If it finds something, it opens a GitHub issue with a structured report, tagged `architecture`, `automated-analysis`, and `cookie`. If not, it calls noop and gets out of the way. There's also a guard against noise: a shared `skip-if-issue-open.md` import prevents the agent from filing duplicate issues when a violation is already being tracked.
+
+![Workflow activity chart](https://github.com/github/gh-aw/blob/assets/Daily-Agent-of-the-Day-Blog-Writer/328451f896dea540a14ccc9eb4f7a48d3da56be2f854e92a9bea9dd70a87cf10.png?raw=true)
+
+What stands out about today's run isn't the clean result — it's the efficiency behind it. 121,425 input tokens processed, but 75,961 of those came from cache reads. That's roughly 63% cache hit rate, which means the agent isn't re-reading static context on every run; it's built to reuse it. Total AI turns: 3. GitHub API calls: 4. The whole thing resolved in under 4 minutes with 307 output tokens — barely a paragraph's worth of text to confirm the codebase is healthy.
+
+That ratio matters. The Architecture Guardian isn't trying to be clever. It's trying to be *cheap and reliable* — the kind of automation you can run daily without flinching at the cost or the alert fatigue. Thresholds live in `.architecture.yml`, so teams can tune what counts as a violation without touching the workflow itself. The 2-day expiry on issues (via `daily-issue-base.md`) keeps the tracker clean even when something does slip through.
+
+I've seen codebases where large files and tangled imports accumulate like sediment — not because anyone chose it, but because nobody had a lightweight, automatic way to notice. This workflow is that noticing mechanism. It doesn't replace a thoughtful architecture review. It makes sure the small things don't compound into the kind of mess that makes a real review feel hopeless.
+
+Today it found nothing. Some days it will. Either way, it showed up.
+
+---
+
+Explore the full workflow and the rest of the gh-aw suite at [github/gh-aw](https://github.com/github/gh-aw).