DEV Community: Google Developer Group

Architecture Documentation as a First-Class Engineering Asset

Alexander Tyutin — Thu, 16 Apr 2026 09:49:24 +0000

How autonomous AI agents can generate a complete architecture snapshot of your microservices platform - while you do push-ups - and why that documentation becomes the most powerful input for your AI-driven quality pipeline.

TL;DR

Architectural documentation is not a chore. When colocated with your source code and fed into an AI-powered quality pipeline, it transforms static analysis from "catching typos" into "catching systemic security failures and costly infrastructure leaks." This article documents a real experiment where an autonomous AI agent generated architecture files across a multi-service Google Cloud platform - with the human engineer largely off-screen - and what happened when that documentation gave our AI Quality Gate an entirely new perspective.

1. The "Self-Documenting Code" Problem

There is a persistent assumption in software engineering that well-structured code is self-explanatory. Clean functions, good variable names, and a Pylint score of 10.0/10 - surely that's enough?

It is not.

Code describes how a system executes. Architecture documentation describes why a system exists and how it interacts with everything around it. Without this context layer, every automated analysis tool is operating in the dark. It sees a function, but not its role in the broader service mesh. It sees an API call, but not the security boundary it is expected to enforce.

This distinction matters enormously when you introduce AI-powered tools into your engineering workflow. An LLM analyzing raw code without architectural context is like asking a senior engineer to perform a security review without access to the system design.

2. Generating Architecture While Doing Push-ups

My platform runs on Google Cloud. It consists of dozens of microservices deployed on Cloud Run, interacting via REST APIs, persisting assets to Google Cloud Storage, and routing all AI operations through a centralized Vertex AI gateway. A rich, well-connected system - but one where the only documentation was spread across scattered README files.

I set out to change that. The goal: a standardized, machine-readable architectural snapshot for every service, committed directly to the repository.

The method: guided autonomous agent execution.

The engineer set a direction, established the documentation standard, and then stepped back. The AI agent - powered by Gemini 3 Flash and Claude Sonnet 4.6 running inside Antigravity, an agentic AI coding assistant - took over. It autonomously inspected each service, read the source code, traced inter-service dependencies, cross-referenced existing implementations against the documentation standard, and iteratively generated structured ARCHITECTURE.md files. The engineer's main activity during most of this process was physical exercise.

The output was not informal notes. It was a disciplined, multi-level documentation hierarchy:

📦 platform-root
 ┣ 📜 ARCHITECTURE.md           ← Level 0: Global service mesh, topology, lifecycle status
 ┗ 📂 services
    ┣ 📂 core-ai-gateway
    ┃  ┗ 📜 ARCHITECTURE.md     ← Level 1: Security policy engine, FinOps guardrails
    ┣ 📂 orchestration-bot
    ┃  ┗ 📜 ARCHITECTURE.md     ← Level 1: Async task flow, Telegram webhook handling
    ┣ 📂 media-transcriber
    ┃  ┗ 📜 ARCHITECTURE.md     ← Level 1: Speech-to-Text pipeline, GCS asset management
    ┗ 📂 translation-engine
       ┗ 📜 ARCHITECTURE.md     ← Level 1: Structured output, multilingual routing

Each document followed a strict template:

Intent: The concrete business and technical reason this service exists.
Design Principles: Key trade-offs - statelessness, latency targets, fallback strategies.
Interaction Diagram: A Mermaid graph of service-to-service flows, security boundaries, and AI provider integrations. It may be generated by the agent and automatically drawn in Gitlab.
LLM Context Block: A precise summary optimized for consumption by automated agents and AI reviewers.

The entire operation resulted in a navigable, cross-linked architecture map - built with minimal human cognitive effort (and with visualizations!)

3. The Quality Gate Awakening

Once the documentation was committed alongside the source code, I ran a standard CI quality review using our AI-powered Quality Gate - a service built on top of Gemini via Vertex AI, designed to perform automated architectural and security reviews on every merge request.

💡 What is the Quality Gate, exactly?
It is not a $100,000 enterprise SaaS platform. It is a lightweight, purpose-built microservice - part of the same platform it reviews - deployed on Google Cloud Run. It exposes a single endpoint, receives the merge request diff from the CI pipeline, constructs an LLM prompt enriched with the repository's architectural documentation, calls Vertex AI (Gemini), and returns a structured JSON review report.

Because it runs on Cloud Run, it starts only when a review is triggered and shuts down immediately after. The total monthly cost for me is a few dollars - a fraction of a single human code review hour. This is a practical demonstration of the Google Cloud serverless model: pay only for the compute you actually use, and use high-intelligence AI only when it adds value.

The difference was immediately visible.

Previously, without architectural context, the Quality Gate was limited to code-level analysis: style consistency, common security anti-patterns, dependency versions. Useful, but shallow.

With the ARCHITECTURE.md files available as context, the model could see the architecture and the code simultaneously. The result was a qualitative leap: the Quality Gate shifted from a static analysis tool into a reasoning system operating at the level of system design.

It identified two critical issues within minutes - issues that had existed undetected in the codebase for months.

Finding 1: The Distributed Tracing Blackout

One of our routing services included middleware that explicitly stripped incoming trace headers. On the surface, this looked like a reasonable security measure to prevent external clients from injecting trace identifiers into internal systems.

The Quality Gate identified it as a critical observability violation.

Because the architectural documentation described the distributed tracing standard across the mesh - including the requirement for end-to-end X-Trace-ID propagation compatible with Google Cloud Trace - the model understood that stripping these headers at the boundary did not isolate a threat. It severed the trace chain entirely. In any production incident, engineers would be unable to correlate logs across services in Cloud Logging, turning a routine debugging session into a multi-hour forensic investigation with no Cloud Audit Logs correlation to lean on.

Security intention ✓. Systemic consequence ✗. The documentation made this contradiction visible.

Finding 2: The Silent Storage Leak

A media processing service was documented as intentionally skipping cleanup of temporary assets in Google Cloud Storage after each processing job. The rationale was implicit - simplicity, no failure modes from deletion errors.

The Quality Gate cross-referenced this against the documented architectural principle of data minimization and least-privilege access, and flagged it as both a security and FinOps violation.

The impact: user audio files - potentially containing sensitive personal information - accumulating indefinitely in cloud storage. No lifecycle policy. No deletion trigger. Silent, compounding cost growth. An expanding attack surface with each new processing request.

Neither a linter nor a code reviewer scanning functions in isolation would have flagged either of these. Both findings emerged from the intersection of code behavior and architectural intent - visible only because the documentation existed.

4. The ROI Case

This experiment produced a measurable return on investment across three dimensions:

Dimension	Without Documentation	With Documentation + AI Agent
Architecture Capture	Senior Architect hours	Agent cycle, near-zero human effort
Review Quality	Code-level findings	System-level and policy findings
Issue Discovery Cost	Post-incident or audit	CI/CD pipeline (minutes, pennies)
Quality Gate	Generic, rigid enterprise tool	Custom microservice, tunable per team or developer

Three additional factors are worth noting specifically in the context of Google Cloud platforms:

Vertex AI Token Efficiency: When the Quality Gate is backed by a Gemini model, providing a structured ARCHITECTURE.md reduces the tokens the model spends reconstructing system intent from raw code. Better context means cheaper, faster, and more accurate generation - directly impacting your AI compute costs.
Cloud Run Observability: The distributed tracing finding described above is particularly relevant for Cloud Run-based architectures, where services are stateless and ephemeral. Without continuous trace propagation, debugging inter-service failures on Cloud Run becomes significantly harder. The documentation made this risk explicit and catchable.
Serverless Cost Model: Because the Quality Gate is a Cloud Run service invoked only during CI/CD runs, there is zero idle cost. On a typical team with several merge requests per day, the entire AI-powered review pipeline costs a few dollars per month - less than a single engineering hour. This is the Google Cloud serverless model working exactly as intended: high-intelligence compute, on-demand, at minimal cost.

5. Lessons for Platform Engineers

The key insight from this experiment is not that AI agents write documentation faster than humans. That is expected. The key insight is that architecture documentation living inside the repository is a force multiplier for every automated tool that reads it.

This applies whether your automated tools are AI-powered code reviewers, compliance scanners, onboarding assistants, or infrastructure planning agents. The better the documentation, the higher the signal quality of every tool operating on top of it.

Practical recommendations:

Colocate documentation with code. A separate wiki that drifts out of sync is noise. An ARCHITECTURE.md in the service directory, updated in the same commit as the code, is signal.
Establish a documentation standard. A consistent template (Intent, Principles, Interaction Diagram) makes documentation machine-readable, not just human-readable.
Define a lifecycle status. Clearly mark deprecated or inactive services. Automated agents should not use legacy code as a reference for current standards.
Use agents to generate the initial draft. The cognitive overhead of starting from a blank page is real. Agents are excellent at producing a structured first pass that engineers then validate and refine.
Feed documentation to your CI pipeline. An AI quality reviewer with architectural context is a different class of tool than one without it.
Build your own Quality Gate - and make it yours. This is the key advantage that enterprise SaaS cannot match: flexibility. A custom Cloud Run service backed by Gemini and driven by your compliance rules, your architectural standards, and your team conventions means every developer can have a personal reviewer that understands the exact context of the project - not a generic ruleset designed for the average of all possible codebases.

6. Conclusion

Architecture documentation has historically been treated as optional overhead - valuable in theory, deprioritized in practice. This experiment demonstrates that when documentation is colocated with source code, follows a consistent machine-readable standard, and is kept current with the help of autonomous agents, it becomes a critical infrastructure component.

It enables automated systems to reason at the level of platform design, not just code syntax. It transforms AI-powered quality gates from expensive linters into genuine architectural advisors. And it can be generated - for an entire platform - while you are doing something else entirely.

The $10,000 ARCHITECTURE.md is not a metaphor. It is the estimated cost differential between finding a critical architectural flaw in a 5-minute CI review versus discovering it during a production incident, a compliance audit, or a cloud storage invoice that nobody expected.

Keep your architecture documented. Keep it in the repository. Let agents maintain it.

Stay standardized. Stay secure.

Using OpenCode as a fallback agent for Antigravity

Alexander Tyutin — Wed, 15 Apr 2026 10:45:53 +0000

Today I was confused by Antigravity errors about high load on their services. It made my work impossible even with the cheapest model Gemini 3 Flash.

Some time ago I heard something about the OpenCode. And it was the time to try it!

I've installed the opencode in my system by brew install anomalyco/tap/opencode and respective extension from the marketplace.

I have a good documentation inside the repo like described in the article Specification-First Agentic Development: A Methodology for Structured, Traceable AI-Assisted Development. So the default free OpenCode model Big Pickle performed planning, reviewing and coding stage well.

But then I realized that it was working without taking into the account system instruction and rules which I had for Antigravity.

So I've performed calls of Antigravity assurance workflows (like here and here) right from the OpenCode chat and it performed them perfectly.

As I have a lot of workflows for linting, security check of diff and the whole repo, and especially external self-made security gateway I was sure that the quality of code produced by the OpenCode was good enough and aligned with my codebase.

The only thing I can mention is a redundant file was left after some iterations of testing. But it can be fixed by a good review right after MR creation.

So seems the OpenCode is a good fallback for cases when Google servers are experiencing problems. Also it can by used to save tokens for some kind of tasks.

Gemini Thinking: How "Brainy" Models Unexpectedly Blew My Budget

Alexander Tyutin — Mon, 13 Apr 2026 07:29:03 +0000

Recently, Google notified me that the Gemini 2.0 models I was using are retiring. This was disappointing because my charity project for Technovation Girls, worked perfectly and very cheaply on those models.

I had to find a replacement. While Google recommended Gemini 3.0, those models are still in "preview". Since my project needs high stability, I chose the Gemini 2.5 family, which is already in "General Availability".

The Surprise: Why is it so Slow and Expensive?

Switching was easy because I built my platform to handle model changes and fallbacks automatically. I simply updated my allowed models list and set gemini-2.5-flash-lite as the primary choice.

However, I was shocked by the results:

Requests took much longer to finish.
The quality was barely better.
Token usage exploded.
I saw a massive "system overhead" in my logs.

Before:

After:

The Cause: "Thinking" by Default

After digging into the documentation, I found the reason: all Gemini 2.5 models are "thinking" models. By default, they use as many tokens as possible to "reason" before answering.

My project worked great without this extra thinking. The slight quality boost was not worth the massive increase in latency and cost. I had to find a way to stop the model from thinking "on my dime".

The Technical Hurdle

I discovered that different models have different minimum "thinking budgets". Surprisingly, gemini-2.5-flash-lite has a higher minimum budget (512 tokens) than the more powerful gemini-2.5-flash (only 1 token!).

Model	Min Thinking Budget
Gemini 2.5 Flash Lite	512 tokens
Gemini 2.5 Flash	1 token
Gemini 2.5 Pro	128 tokens

To fix this, I had to expand my code to calculate and limit these budgets during fallbacks. I also had to handle the new text constants (MINIMAL, MEDIUM, HIGH) used by the Gemini 3.x models.

"gemini-2.5-flash-lite": {
           "model_page": f"{_MODEL_GEMINI_DOCS_BASE}/gemini/2-5-flash-lite",
           "is_thinking": True,
           "grounding_rag": True,
           "grounding_google_search": True,
           "count_tokens": True,
           "supports_thinking_level": False,
           "supports_thinking_budget": True,
           "min_thinking_budget": 512,
           "outputs": ["text"],
       },
"gemini-2.5-flash": {
           "model_page": f"{_MODEL_GEMINI_DOCS_BASE}/gemini/2-5-flash",
           "is_thinking": True,
           "grounding_rag": True,
           "grounding_google_search": True,
           "count_tokens": True,
           "supports_thinking_level": False,
           "supports_thinking_budget": True,
           "min_thinking_budget": 1,
           "outputs": ["text"],
       },
"gemini-2.5-pro": {
           "model_page": f"{_MODEL_GEMINI_DOCS_BASE}/gemini/2-5-pro",
           "is_thinking": True,
           "grounding_rag": True,
           "grounding_google_search": True,
           "count_tokens": True,
           "supports_thinking_level": False,
           "supports_thinking_budget": True,
           "min_thinking_budget": 128,
           "outputs": ["text"],
       },

The Result

I finally switched to gemini-2.5-flash with a strict limit of 50 thinking tokens.

Now, response speeds are back up and costs are back down. It was a lot of unexpected work for a "simple" upgrade, but everything is running smoothly again!

I tried to make DevFest Ireland accessible - and ended up building a SaaS

Jordan Harrison — Fri, 10 Apr 2026 13:18:59 +0000

The email I couldn't ignore

A few months into organising DevFest Ireland 2025, I received messages from a couple of deaf developers asking if they could attend.

Not in a vague "looks interesting" kind of way. They wanted to come. They wanted to sit in the talks, meet people, be part of it properly. And the question they asked was completely fair: would there be an Irish Sign Language interpreter?

I didn't have a solid answer for them at the time. I thought it would be one of those things that would take a bit of organising, a few emails, some budget approval, and then get sorted. That was my naive version of it anyway.

It turned out not to be like that at all.

Trying to make it work

Once I started looking properly, I ran into the shortage almost immediately. There simply are not enough ISL interpreters available, especially for full day events. Availability is tight, booking needs to happen early, and the logistics are harder than most people realise from the outside. For a conference, you are not just solving for one slot in a timetable. You are trying to cover a long day, with the practical reality that this kind of work cannot just be dumped onto one person and expected to somehow stretch across everything.

That was the point where it stopped feeling like a normal organiser task and started feeling like a structural problem.

The hardest part was that I now had real people waiting on an answer. I could not hide behind "we're looking into it" in my own head, because that still leaves someone wondering whether they can actually come.

It wasn't only about interpretation

The more I sat with it, the more obvious it became that this was bigger than one accessibility request.

Yes, ISL interpretation mattered. A lot. But so did transcription. And not only for deaf attendees. There are hard of hearing attendees who do not use sign language. There are people who find spoken content much easier to process when they can read along. There are neurodivergent attendees who benefit from seeing the words as well as hearing them. There are remote viewers. There are people trying to follow a technical talk delivered quickly by someone with a strong accent while half the room laughs at a reference they missed.

Once I started thinking about it that way, live transcription stopped feeling like a backup option. It felt central.

The options were not great

So I started talking to captioning and transcription providers.

The split was basically what you would expect, but more frustrating when you are the one making the call. Human captioning looked strong. High accuracy, experienced operators, something you could trust. But it came in at the kind of price that forces a community event to think very carefully about whether it can carry it.

AI captioning was somewhat easier to justify on cost - although it still ran into 4 figures(!) and the quoted level of accuracy just was not good enough for a technical conference. Not with fast speakers, different accents, library names, acronyms, product terms, and all the weird ways developers talk when they are explaining something they know too well.

That was the bit that kept bothering me. The choice seemed to be either spend a lot or accept something that would let people down. That is not much of a choice if the whole point is accessibility.

So I built it

At some stage, after enough comparing and researching and getting annoyed by the gap, I stopped asking who I should buy from and started asking what I actually wanted the software to do.

I wanted live transcription that could keep up with technical talks. I wanted something accurate enough that a person could depend on it instead of politely pretending it was helpful. I wanted it to be affordable enough that smaller events could realistically use it.

I was not thinking "this should be a SaaS." I was thinking "I need this to exist for DevFest."

So I built it.

It started the way a lot of things start: messy, practical, not especially glamorous. A lot of testing. A lot of fixing. A lot of checking the output and asking myself whether I would trust this if I were relying on it to follow a talk. That was the standard that mattered to me. Not whether it looked clever. Whether it actually helped.

From a solution for one event to VolenScribe

That tool eventually became VolenScribe.

VolenScribe is the SaaS that came out of all of this. It does live AI transcription for events, and it grew directly from trying to solve this problem in a way that did not feel half baked. One of the main things I cared about from the start was accuracy, because that is where so many AI transcription products fall apart once you put them in a real room with real people, and making sure it was useful beyond English-only events. VolenScribe supports 25 spoken languages, so it can be used across the world.

The AI transcription model used by VolenScribe has an average word error rate of 3.9%. That matters to me more than any vague claim about being smart or scalable or next generation or whatever else people like to say. The actual question is simpler: if someone is reading these captions, can they follow what is being said without constantly correcting the machine in their head?

That is the bar.

What actually mattered here

The strange thing is that I never set out to build a company around this. It came from a very specific problem, at a very specific event, because a few people asked a very reasonable question and I realised I did not have a good answer.

I think that is why this has stayed with me.

Accessibility is often talked about in broad, well-meaning terms, but the reality is much more direct than that. Someone wants to attend. Someone wants to follow the talk. Someone wants to feel like the event was built with them in mind too. Either they can, or they cannot.

That is what all of this came down to in the end.

Why I'm still thinking about it

I do not think organisers should have to choose between something expensive and something unreliable. I do not think accessibility should become one of those things people care about right up until the invoice lands. And I definitely do not think the answer should be "well, this is the best we could do" when the result still leaves people out.

Volenscribe started because I could not find something I trusted enough to use.

It just happened that solving that for DevFest Ireland 2025 turned into something other people needed too.

And really, it all goes back to those first messages. A few deaf developers reached out because they wanted to be there. Everything that came after, including the software, came from taking that seriously.

AI-Powered Repository Security Check with Antigravity Workflow

Alexander Tyutin — Mon, 06 Apr 2026 09:46:09 +0000

When teams want to "move fast and break things," security is often the first thing they forget. I've seen a lot over 15 years in the industry. My approach is simple: follow the Pareto Principle (80/20). You want 80% of the security results with just 20% of the work.

In the AI era, that 20% of work can look like a single command.

Here is how we built the Antigravity workflow that checks the whole repository for security issues in several minutes. It does not cost much and does not use up all the AI's context window.

Short video demo made on a real repository:

The Initial Stack

To get a clear picture of a repository's health, one tool is not enough. We use a combination of proven, open-source scanners for the beginning:

Gitleaks: To find secrets like API keys and tokens.
Semgrep: For SCA and SAST to find bad code patterns and supply chain issues.
Checkov: To check IaC security (Docker, Terraform, Kubernetes).
OSV-Scanner: For SCA scan.

Inspecting their results manually takes a lot of time. And if you just send all their raw output directly to an AI, it becomes very expensive and confusing.

Token Economy

For a security review, the AI doesn't need to see every test that passed. It doesn't need to see the full abstract syntax tree. It only needs to know what is broken, where it is, and why it matters.

We use jq to remove the extra noise. This minifying step is very important for Token Economy.

To increase the token savings the command (workflow) may be ran with the cheapest Gemini 3 Flash. It is more than enough to receive a high-quality base report. Then the report may be reviewed with more powered models like Gemini 3.1 Pro.

Example: Minifying Results

Instead of a huge JSON file per tool, we make it small and simple. For example, here are the exact commands we use to make the results smaller:

  1. `jq '[.[] | {rule: .RuleID, file: .File, line: .StartLine}]' gitleaks-raw.json > gitleaks-min.json`
  2. `jq '[.results[] | {rule: .check_id, file: .path, line: .start.line, severity: .extra.severity}]' semgrep-raw.json > semgrep-min.json`
  3. `jq 'if type=="array" then map(.results.failed_checks[]) else .results.failed_checks end | [.[]? | {rule: .check_id, file: .file_path, line: .file_line_range}]' checkov-raw.json > checkov-min.json`
  4. `jq '[.results[]?.packages[]?.vulnerabilities[]? | {rule: .id, file: .package.name, line: "N/A", severity: ((.database_specific.severity) // "N/A")}]' osv-raw.json > osv-min.json`

By making the data 90% smaller, the AI stays focused on real problems. This makes the check much cheaper.

% ls -lh .security-artifacts | awk '{print $5, $9}'

6.3K checkov-min.json
2.6M checkov-rev-004-security-20260401-201110.json
2.4K gitleaks-min.json
19K gitleaks-rev-004-security-20260401-161824.json
19K gitleaks-rev-004-security-20260401-201110.json
107B osv-min-rev-001-security-20260406-110805.json
11K osv-raw-rev-001-security-20260406-110805.json
4.3K semgrep-min.json
61K semgrep-rev-004-security-20260401-161824.json
38K semgrep-rev-004-security-20260401-201110.json

The "One Command" Workflow

We put all these steps into one Antigravity slash command: /review-security-repo.

When we run it, the agent does exactly this:

Identifies the environment: Checks for tools like semgrep, gitleaks, checkov, osv-scanner and jq.
Executes Raw Scans: Runs the scanners to get raw logs.
Applies Minification: Uses jq to strip massive metadata.
Synthesizes Findings: Only reads the small files (gitleaks-min.json, semgrep-min.json, checkov-min.json, osv-min.json).
Performs Review: Checks high-risk files to find complex problems that static tools miss.
Generates an Actionable Report: Uses a strict Markdown structure instead of a generic summary.

Report Structure Snippet

The workflow forces the AI to output exactly what we need, like this:

### [Severity] - [Vulnerability Name/Rule ID]
- **Tool Source:** [Semgrep / Gitleaks / Checkov / Manual Architectural Review]
- **Location:** `[File Name]:[Line Number]`
- **Business Impact:** [Why this matters]
- **Remediation:** 
  [Actionable, copy-paste code or config fix]

Why This Works

Repeatability: Anyone on the team can check security without being an expert.
Audit Trail: Every raw and minified report is moved to .security-artifacts/ so we can track the history.
Reduced Hallucinations: Because we give AI only the exact scanner results and small code pieces, it gives real fixes without making things up.

Full Workflow Code

If you want to try this yourself, here is the complete code for the /review-security-repo workflow:

---
description: "Security review of the repo"
---

- Get the current branch name and current timestamp (format: YYYYMMDD-HHMMSS). Define output file as `security-review-[branch-name]-[timestamp].md`.
- Check for a `venv` (or `.venv`) directory in the repository root. If found, use its binaries.
- Verify if `semgrep`, `gitleaks`, `checkov`, and `jq` are installed. If missing, prompt for installation and pause until confirmed.
- Execute local security scanners to capture raw audit trails:
  1. `gitleaks detect --source . -v --report-format json --report-path gitleaks-raw.json`
  2. `semgrep scan --config auto --json --output semgrep-raw.json`
  3. `checkov -d . --quiet --skip-path venv -o json > checkov-raw.json`
  4. `osv-scanner -r . --format json > osv-raw.json || true`
- Execute `jq` to strip massive metadata, passed checks, and AST dumps, keeping only critical fields to save context tokens:
  1. `jq '[.[] | {rule: .RuleID, file: .File, line: .StartLine}]' gitleaks-raw.json > gitleaks-min.json`
  2. `jq '[.results[] | {rule: .check_id, file: .path, line: .start.line, severity: .extra.severity}]' semgrep-raw.json > semgrep-min.json`
  3. `jq 'if type=="array" then map(.results.failed_checks[]) else .results.failed_checks end | [.[]? | {rule: .check_id, file: .file_path, line: .file_line_range}]' checkov-raw.json > checkov-min.json`
  4. `jq '[.results[]?.packages[]?.vulnerabilities[]? | {rule: .id, file: .package.name, line: "N/A", severity: ((.database_specific.severity) // "N/A")}]' osv-raw.json > osv-min.json`
- Read ONLY `gitleaks-min.json`, `semgrep-min.json`, `checkov-min.json`, `osv-min.json`. Filter out false positives based on repository context.
- Analyze high-risk architectural files strictly for logical flaws and cross-service least-privilege violations that static tools cannot understand.
- Generate the report in `security-review-[branch-name]-[timestamp].md`. DO NOT output generic summary tables. You MUST output an exhaustive, itemized list.
- Use the following strict Markdown structure for the report:
  ## Executive Summary
  [Brief overview of the branch's security posture]
  ## Detailed Findings
  [Iterate through EVERY validated finding. For each finding, output:]
  ### [Severity] - [Vulnerability Name/Rule ID]
  - **Tool Source:** [Semgrep / Gitleaks / Checkov / Manual Architectural Review]
  - **Location:** `[File Name]:[Line Number]`
  - **Business Impact:** [Why this matters]
  - **Remediation:** 
    ```


    [Actionable, copy-paste code or config fix]


    ```
- Create a `.security-artifacts/` directory if it does not exist. Ensure `.security-artifacts/` is appended to `.gitignore`.
- Move and rename both raw and minified reports to `.security-artifacts/` to preserve the complete historical audit trail:
  - `gitleaks-raw.json` -> `.security-artifacts/gitleaks-raw-[branch-name]-[timestamp].json`
  - `semgrep-raw.json` -> `.security-artifacts/semgrep-raw-[branch-name]-[timestamp].json`
  - `checkov-raw.json` -> `.security-artifacts/checkov-raw-[branch-name]-[timestamp].json`
  - `osv-raw.json` -> `.security-artifacts/osv-raw-[branch-name]-[timestamp].json`
  - `gitleaks-min.json` -> `.security-artifacts/gitleaks-min-[branch-name]-[timestamp].json`
  - `semgrep-min.json` -> `.security-artifacts/semgrep-min-[branch-name]-[timestamp].json`
  - `checkov-min.json` -> `.security-artifacts/checkov-min-[branch-name]-[timestamp].json`
  - `osv-min.json` -> `.security-artifacts/osv-min-[branch-name]-[timestamp].json`
- Exit execution.

What’s Next?

What tools are missing from your perfect "One Command" security check? Will be happy to receive opinions on how to further optimize the token economy while expanding the security coverage.

Scaling Product Discovery: Orchestrating AI Agent Workflows with Google Opal

Sandro Moreira — Sun, 05 Apr 2026 14:52:06 +0000

Introduction: The Challenge of Relevance in Software Development

Developing an application is one thing; creating one that users actually want to use is another. The difference lies in the depth of your understanding of the pains, desires, and unmet needs of your target audience. Too often, development begins with a solution looking for a problem.

I recently embarked on a journey to optimize my product discovery process, moving from time-consuming manual methods to an AI-assisted application building workflow. My mission? To build a flow that not only generated ideas but deeply validated them against the real sentiment of the market.

The Flow

1 - The Raw Data Collection (Sources): I focused on a specific topic of interest and fed NotebookLM's source feature with complex data:

User Pains: Documents extracted from forums (Reddit, communities) to investigate pains unresolved by existing solutions.
Market Trends: Articles and research on emerging trends (e.g., generative AI integration, specialized niches).
Competitive Analysis: Detailed reviews and descriptions of competitor applications.

2- Information Cross-Referencing and Analysis: NotebookLM excelled at finding connections. By asking the model to cross-reference data, I could quickly identify patterns of complaints and resource gaps in the market.

3- Generating Strategic Insights (Prompts): I used structured analysis prompts to synthesize the data into actionable insights: "Cross-reference market trends with competitor features and identify a feature that is in high demand, but has low coverage in the market."

4 - The MVP Conception (Final Prompt): The final step was generating a highly refined MVP prompt, ready for development:
"Generate an MVP documentation (including Target Audience, Value Proposition, and 3 Essential Features) that addresses pain X, aligns with trend Y, and offers feature Z (low/non-existent coverage). The goal is for this MVP to be built on Gemini 3.0."

Scaling Discovery with Google Opal

The initial validation phase using NotebookLM was an insightful experiment, but it still required significant manual intervention. Now, it’s time to evolve this workflow into a truly automated engine.

This led me to Google Opal, the platform designed to turn complex logic into visual, multi-step AI Workflows (or mini-apps). While the concept mirrors the functionality of AI Agents - systems that take action autonomously - Opal provides the no-code workflow pipeline for orchestrating these steps reliably.

In Google Opal, the goal is to create a product discovery agent pipeline that operates continuously.

Step 1 - The Search: At external sources (forums, reviews) to filter and feed new pain signals and trends.

Step 2: The Analyst: Analyzes data from phase 1 against competitive data to generate strategic gaps and novel feature ideas.

Step 3: The Strategist: Converts the strategic report into the final assets for development and business.

Here is the step-by-step breakdown of how I configured the three core agents in Google Opal, turning a simple workflow into an autonomous pipeline.

Step 1: The Search (Data Ingestion)

This step is the system's eyes and ears, responsible for ingesting and pre-filtering raw market data.

1 - Topic of Interest: UserInput Initially empty node where the user enters the topic of interest.

2 - Search Users, Trends and Competitors: Generate Nodes for search with specific prompts

3 - Users Opinion, Trends and Competitors: OutPut (Google Docs)

Each output node I specified "Save to Google Docs" and set a name for the file in Advanced Settings.

Step 2: The Analyst (Insight Generation)

This is the brain of the operation, where raw data is turned into strategic intelligence.

1 - Analyze Problems: Generate

2 - Strategic Analysis: Generate

3 - Pain Points: OutPut (Google Docs)

4 - Strategic Analysis: OutPut (Google Docs)

Step 3: The Strategist (MVP & Pitch Generation)

The final takes the distilled strategy and turns it into deliverable assets for developers and stakeholders.

1 - Ideas App Generate

2 - MVP Recommendation Generate

3 - Generate Pitch Generate

The nodes are connected to other OutPut (Google Docs) (Ideas, MVP Recommendation) for creating files in Google Docs and the node Pitch has type OutPut (Google Slides)

And finally, the last step where we add a node to generate the Prompt for Gemini 3, another with an HTML output showing the result of the entire flow execution.

Conclusion: From Idea to MVP in Minutes

1 - Prompt to App: Generate

2 - Prompt for Gemini 3.0: OutPut (Google Docs)

3 - Generate HTML: OutPut (Manual Layout)

It transforms your workflow into an innovation pipeline quickly, ensuring that your next application not only meets a market need but is designed to address a real problem the market is actively complaining about.

By leveraging the power of agents and workdflows, we can move from market insight to a complete, validated, and ready-to-code MVP specification in minutes, significantly de-risking the development process.

opal.google

To create the MVP, simply use the generated prompt and run it in the Build tab of ai.dev, letting Gemini build it for you.

Want to put it into production? Use the icon in the upper corner of the built app screen to send it directly to Google Cloud.

Cross-Repository Development with Antigravity

Razan Fawwaz — Thu, 02 Apr 2026 02:26:20 +0000

If you've been sleeping on Antigravity, now's the time to wake up. Google's latest IDE isn't just another code editor — it comes with a built-in AI Agent Manager, meaning you can write code, run unit tests, spin up files, and execute everything directly, all while an AI assistant handles the heavy lifting alongside you. You can even plug in MCP Servers to pass richer context to the Agent.

Honestly? With Antigravity, you can kick off a task and go fishing. I'm not even joking.

The Problem with Scaling

Out of the box, Antigravity tends to scaffold projects using fullstack frameworks like Next.js or Vite + React. For smaller projects, that's totally fine — convenient, even.

But once you start scaling, a single monorepo starts to feel like a liability. The codebase bloats, separation of concerns gets blurry, and things that should be independent start bleeding into each other. Personally, I much prefer keeping frontend and backend as separate repositories. Shoutout to Kak Ishfa for pushing me to think about this more seriously.

Here's the catch though — Antigravity doesn't have a native Linked Workspace feature. There's no built-in way to point a single Agent at two separate repositories and have it work across both seamlessly.

But there's a workaround, and it's cleaner than you'd expect.

The Workaround: Agent Rules

The trick is using Agent Rules — a feature that lets you define behavior the Agent always follows, regardless of what you're asking it to do.

The idea is simple: open your frontend repository in Antigravity, then write a rule that tells the Agent about your backend repository's directory path. From that point on, whenever a frontend change requires a corresponding backend update, the Agent knows exactly where to go and what to touch.

Here's how I set it up: I have two repos, frontend and backend. In the frontend project, I added a rule that says — in plain language — "if any feature change requires backend work, update the backend repository too." The key detail is setting the activation mode to always on, so the Agent checks the rules on every single interaction, not just when you explicitly tell it to.

Here's a rough idea of what the rule content looks like:

You are working on a frontend project located at /path/to/frontend.
There is a paired backend project located at /path/to/backend (Go, net/http, SQLite).
Whenever a frontend change requires an API or backend change, apply those changes
to the backend project as well. Always keep both repositories in sync.

Simple, readable, and it works.

Putting It to the Test

To try this out, I built a todo app — login, full CRUD, connected to a Go + net/http + SQLite backend. Both directories started completely empty.

Once I submitted the prompt, Antigravity picked up the rules immediately and asked for approval before touching anything. After confirming, it installed the necessary packages and kicked off development — starting with the backend.

With the backend done, it seamlessly transitioned to the frontend and set up Vite + React.

When the chat stopped and the "accept all" button appeared, both projects were fully scaffolded and in sync — exactly as intended.

Wrapping Up

Is this the most elegant solution? Not really — ideally Antigravity would ship a proper Linked Workspace feature. But as a workaround, Agent Rules gets the job done surprisingly well. It's flexible, easy to set up, and once it's in place you barely have to think about it.

If you're working with separate repositories in Antigravity, give this a shot. It might just change how you build.

#Antigravity

Antigravity: My Approach to Deliver the Most Assured Value for the Least Money

Alexander Tyutin — Wed, 01 Apr 2026 05:49:34 +0000

As I'm not a professional developer but a guy who needs to use automation to get things done, I follow one main rule: keep it simple. Overengineering hurts. I use the Pareto rule—spend 20% of the effort to get 80% of the result.

When I use AI agents like Antigravity, my goal is not to let the AI write complex code that no one can read. My goal is to build simple, secure features fast. At the same time, I control costs by saving tokens. Here is the exact workflow I use.

The Token Economy Strategy

LLM tokens cost money. Using a smart, expensive model just to fix code spaces is not worth the cost. I change models based on how hard the task is.

High-Tier Models: They are for the big tasks: planning architecture, writing complex business logic, checking security, and counting cloud costs.
Low-Tier Models: These folks are for simple tasks: fixing syntax errors, aligning code to Pylint, and writing standard code pieces.

Task Decomposition & In-Repo Architecture

Large prompts can break LLMs. If a prompt has too much text, the AI gets confused and wastes tokens. To stop this, I break every task into small, separate pieces so the AI only sees what it needs.

I store all architecture plans and tasks inside the code repository (for example, ./docs). This keeps the instructions very close to the code for the AI.

Every task I write uses this strict four-part structure:

Idea: The main business or tech goal. Why it matters: It proves the task is useful before I spend tokens for delivering a code to review.
Plan: The technical blueprint. Why it matters: It locks down the plan, keeps security high, and stops the AI from inventing bad solutions.
What Was Done: A short log of the work. Why it matters: It gives future AI tasks a quick summary, so the AI does not have to read every code file again.
Debt: A list of any technical shortcuts or "crutches" used to save time. Why it matters: Hidden debt ruins the project. Important: My custom Quality Gate checks this section. If it finds unapproved shortcuts in the code, it blocks the release completely.

System Instructions for the AI

To keep the AI agent aligned with the goals, I pass strict system instructions on every run. It never lets the model guess my coding standards. Here are the core rules enforced:

No Crutches: Any "crutch" or technical shortcut must be approved by me. Then, the AI must document it as technical debt in the project files.
No Inventing Wheels: I try hard to avoid this. If a working approach already exists in another project, the AI reuses it.
Learn from the Past: When building a new service, the AI must check the old tech debt to avoid repeating past mistakes.
Simple Code Only: The code structure should just use standard classes. I avoid "genius-level" extreme one-line code tricks or overwhelming structures.
Maintainability First: A middle-level, part-time developer must be able to read and maintain the code.

The Core Workflow

Every feature goes through a step-by-step process. I'm trying to keep security and simplicity as the main focus at each step.

1. Plan & The Plan Review

Using a High-Tier Model.

Plan: Defining the code structure, the security rules, the cost limits, etc. I make sure not to add to old technical debt.
Review: I look at the plan with a "fresh eye." I do not start coding until the plan is clear with main code snippets planned.

2. Code & Code Review

Using a Low or Mid-Tier Model for code and Mid or High-Tier Model for review.

Code: Implement the code exactly as planned. Use clear classes and avoid complex, one-line code tricks. A middle-level developer must be able to maintain it easily.
Review: Make sure the code matches the rest of the project. I prefer another "person" to check it before I call it done.

3. Lint & Quality Gate

Using Free External Tools & A Custom Nanoservice.

Lint: I do not pay LLMs to fix missing spaces. I use free tools like autopep8, ruff, and pylint to save tokens.
Quality Gate: I built a simple nanoservice using the Vertex API. It checks the code changes against the main branch. It works like an automatic review from the CTO, CISO, and CFO. It checks every line for good architecture, proper security access, and cost impact before the code goes to production. Why is it so important? The Quality Gate is not overwhelmed by the full chat history inside the IDE. Its "fresh eye" often finds architectural and coding flaws that were missed by the IDE models, even after 6 to 9 rounds of review.

The Bottom Line

AI coding is not magic. In my experience, it requires a strict testing gate, smart model swapping, and simple design. By owning the process and letting the AI act as a typist, it is possible to ship secure code fast. I share this approach for an open discussion on how we can build better automation.

Managing Secret For Your Golang Apps With The GCP Secret Manager

Razan Fawwaz — Wed, 01 Apr 2026 05:02:19 +0000

While developing a serverless application and having a secret key in JSON format, I always looked at how we store that file securely. We can’t save the JSON file in our public repository, right? ☠️

Since I plan to deploy the application using Google Cloud Run, I’ve found that Google Cloud has a Secret Manager service!

Store API keys, passwords, certificates, and sensitive data

Secret Manager is a secure and convenient storage system for API keys, passwords, certificates, and other sensitive data

Google Cloud

With Secret Manager, we can store the credentials to the Secret Manager and integrate our application to “take” the credentials from the Secret Manager.

There are two ways to store the secret, we can use the console or CLI, for this time I will use the CLI.

For example, I have a simple Golang app that has a file called secret-key.json for authentication to database services. I want to deploy the application using Cloud Run and using the secret key that is provided so the service can communicated to the database.

I already downloaded the key and am ready to put it on Secret Manager. First of all, make sure your devices are already authenticated with your Google Cloud account.

You can log in to your account by using this command

gcloud auth login

After that, set to using your project

gcloud config set project <PROJECT_ID>

The next step is we should enable the API of the Secret Manager service. You can use this command to enable it.

gcloud services enable secretmanager.googleapis.com

If the message returns “Operation …….. finished successfully” now we’re ready to go 🚀

Now, we’re heading to the directory where we store the secret key, or you can use any directory and set it the path on the command, here is the command that we will use

gcloud secrets create <SECRET_NAME> --data-file=<SECRET_FILE_PATH>

The image below shows the results if we already created the secret in Secret Manager.

Or you can check it from the Google Cloud Console and go to the Secret Manager page.

Now this is the Go code looks alike, since we just need to read the data, the process on this code is just to retrieve the secret. You should fill out the GOOGLE_CLOUD_PROJECT_NUMBER you can hardcode it or use OS Env.

package main
import (
 "context"
 "log"
 secretsmanager "cloud.google.com/go/secretmanager/apiv1"
 "cloud.google.com/go/secretmanager/apiv1/secretmanagerpb"
)
func main() {
 projectNumber := os.Getenv("GOOGLE_CLOUD_PROJECT_NUMBER")
 secretName := os.Getenv("SECRET_NAME")
 ctx := context.Background()
 client, err := secretsmanager.NewClient(ctx)
 if err != nil {
  log.Fatalf("failed to setup client: %v", err)
 }
 defer client.Close()
 accessRequest := &secretmanagerpb.AccessSecretVersionRequest{
  Name: "projects/" + projectNumber + "/secrets/" + secretName + "/versions/latest",
 }
 result, err := client.AccessSecretVersion(ctx, accessRequest)
 if err != nil {
  log.Fatalf("failed to access secret version: %v", err)
 }
 secret := string(result.Payload.Data)
 log.Printf("secret: %s", secret)
}

While running it locally, don’t forget to authenticate the program with the Google Cloud Project by using this command. For more reference, you can check this out.

gcloud auth application-default login

Then, you can run the program using go run main.go and here we go, this is the secret that we stored it before!

If you want to deploy it to Cloud Run, you can try this code

package main
import (
 "context"
 "fmt"
 "log"
 "net/http"
 "os"
 secretsmanager "cloud.google.com/go/secretmanager/apiv1"
 "cloud.google.com/go/secretmanager/apiv1/secretmanagerpb"
)
func main() {
 projectNumber := os.Getenv("GOOGLE_CLOUD_PROJECT_NUMBER")
 secretName := os.Getenv("SECRET_NAME")
 ctx := context.Background()
 client, err := secretsmanager.NewClient(ctx)
 if err != nil {
  log.Fatalf("failed to setup client: %v", err)
 }
 defer client.Close()
 accessRequest := &secretmanagerpb.AccessSecretVersionRequest{
  Name: "projects/" + projectNumber + "/secrets/" + secretName + "/versions/latest",
 }
 result, err := client.AccessSecretVersion(ctx, accessRequest)
 if err != nil {
  log.Fatalf("failed to access secret version: %v", err)
 }
 secret := string(result.Payload.Data)
 http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
  fmt.Fprintf(w, "Your secret is: %s", secret)
 })
 log.Fatal(http.ListenAndServe(":8080", nil))
}

razanfawwaz / go-gcp-secret

Go Apps using Secret Manager

go-gcp-secret

View on GitHub

Don’t forget to put the Env Variables while setting up the Cloud Run deployment.

If the deployment succeeds, you can try to call the “/” endpoint, and it will return the secret key that we need.

Additionally, if the Cloud Run needs access to the Secret Manager, you can go to the Secret Manager and give access to your Cloud Run Service Account by clicking Add Principal.

That’s all! 🚀 Thanks for reading!

Scaling your productivity with spec docs in your IDE - Anti Gravity.

Matthew Christiansen — Thu, 26 Mar 2026 21:49:41 +0000

Google’s Anti Gravity is built on a simple premise: remove friction so developers can stay in "the flow." But the real unlock isn’t just the IDE itself, it’s how you architect your interactions with the AI inside it. While this article is relevant for any IDE you are using with AI, if you aren't using it yet, I would recommend you take a look at Anti Gravity.

What I am doing with my IDE and AI now:
I’ve started moving away from "chatting" with AI. Instead, I’ve been creating small .md files that act as Instruction Layers for Gemini. This simple shift turns an LLM from a conversational assistant into a predictable, modular part of my technical stack.

The Core Concept:

Prompts as Configuration
Instead of re-explaining my requirements every time I open a terminal, I treat prompts like Angular Components. I create a simple Markdown file that tells Gemini exactly how to behave for a specific task. There are also versions of doing this in certain tools branded as workflows, skills, rules, etc but the premise really is just writing something down easily referencable by your ide to regularly bring into your AI prompts without re-writing that will point your LLM in the right direction when helping with code.

When you find yourself prompting the same thing multiple times, whether in Anti Gravity or any integrated IDE, you shouldn't be typing; you should be referencing a spec and updating it.

An "Angular-Style" Instruction File:

Encapsulated: A clearly defined purpose.
Reusable: Use it across any feature branch.
Consistent: Standardized output every single time.

Example: pr-assistant.md

PR Comment Assistant

Goal:
Draft and post high-quality GitHub PR comments via the git CLI.

Rules:
Keep feedback actionable, professional, and concise.
Call out uncertainty explicitly; no speculation.

Structure:
Context → Suggestion → Reasoning.

Execution:
Output via git CLI; do not use inline IDE comments.
Treat comments as notes for reviewers and future contributors.

Why This Works (Anti Gravity in Practice):
Without structure, you suffer from Prompt Drift. Your instructions get lazy, the output becomes inconsistent, and you repeat yourself constantly.

By using .md instruction files, you achieve Cognitive Offloading:

Predictability:
Gemini follows the spec, not the "vibe" of your last message.
Efficiency:
You stay focused in your IDE, invoking capabilities rather than brainstorming prompts.
Scalability:
These files live in your repo. They evolve with your codebase, they’re version-controlled, and they can be shared across your entire team.
Angular as the Language of Focus:
This approach mirrors core Angular principles almost perfectly:
Separation of Concerns:
Each .md file has one specific job. Reusability: The same instruction file works across different PRs and projects.
Consistency:
You get standardized outputs, every time. Instead of just "talking" to an AI, you are composing it into your development environment.

Closing Thought
The real power of Anti Gravity within an Angular codebase isn’t just writing code faster, it’s reducing the mental overhead of the development process.

When you pair a high-performance IDE with small, well-designed instruction files, you get something bigger than an assistant. You get a custom-built, automated collaborator.

When Zero‑Width Isn’t Zero: How I Found and Fixed a Vulnerability

Karol Wrótniak — Wed, 28 Jan 2026 16:01:56 +0000

When you set a max length on a form field or API, you expect it to hold. But what if a four-character string could secretly carry 10,000 extra bytes of invisible data, crashing your database or bypassing your validation? That was the vulnerability I found and fixed in the popular JavaScript library validator. It was a subtle bug involving Unicode Variation Selectors that allowed attackers to inject massive payloads while still passing length checks.

Introduction

The isLength function is simple on the surface: count characters and compare to a limit. But in a Unicode world, “character” is tricky. You need to match the perceived length (what the user sees) with the storage length (what your database handles), or you risk truncation, performance issues, and, as I found, critical bypasses.

Unicode and the illusion of length

JavaScript strings use UTF‑16. Some visible “characters” span two code units (surrogate pairs). isLength adjusts for that. It treats a base character plus a Variation Selector as one perceived character. That’s because the selector only changes the presentation.

// Emoji still count as one perceived character
const smile = '';
console.log(smile.length);          // 2 (UTF-16 code units)
// With isLength, it's treated as 1

The attack vector: Variation selectors gone wild

Variation Selectors (U+FE0F, U+FE0E) tweak how a base character displays. They aren’t content on their own. The old logic subtracted all selectors. So one can pad a short string with thousands of them while still passing the check with a low max.

// Apparent 4 chars, but thousands of extra selectors
const s = 'test' + '\uFE0F'.repeat(10_000);
console.log(s.length); // 10,004 (UTF-16)

What are unicode variation selectors?

These are zero‑width code points (U+FE0E for text and U+FE0F for emoji among the others) that modify the presentation of the character that immediately precedes them. They change appearance, not meaning. A base character plus a selector is meant to count as one perceived character.

As of Unicode 17.0, using them to choose emoji vs. text for many legacy dingbat bases is being phased out. The new emojis have separate code points assigned for each style. For example, the emoji 🪯 (U+1FAAF KHANDA) has a dedicated emoji code point. The older dingbat-style symbol is ☬ (U+262C ADI SHAKTI). Variation selectors still exist and work for bases that support them. But modern additions increasingly prefer distinct code points over selector‑based presentation. Unicode provides the emoji presentation sequences chart.

Here are some examples (text vs. emoji):

Heart: ❤︎ (text, U+2764 U+FE0E) vs ❤️ (emoji, U+2764 U+FE0F)
Airplane: ✈︎ (text, U+2708 U+FE0E) vs ✈️ (emoji, U+2708 U+FE0F)
Snowman: ☃︎ (text, U+2603 U+FE0E) vs ☃️ (emoji, U+2603 U+FE0F)
Writing hand: ✍︎ (text, U+270D U+FE0E) vs ✍️ (emoji, U+270D U+FE0F)
Telephone: ☎︎ (text, U+260E U+FE0E) vs ☎️ (emoji, U+260E U+FE0F)

Console example:

// Base character: Heavy Black Heart
const heart = '\u2764';
const heartText = heart + '\uFE0E'; // request text style
const heartEmoji = heart + '\uFE0F'; // request emoji style

console.log(heart, heartText, heartEmoji); //  ❤︎

By default, (with no selector), presentation differs by platform, browser, and font. Some show emoji by default; others prefer text. If you need a specific look, add U+FE0E (text) or U+FE0F (emoji). On the web, you can use the font-variant-emoji CSS property.

Important: A selector only makes sense right after a compatible base. Multiple selectors don’t stack or change meaning. ❤︎\uFE0F\uFE0F doesn’t become “more emoji.” Only the first base+selector pair affects the presentation. All the extras are stray code points.

For validation, ignore only one base+selector pair. Count stray or repeated selectors toward length. Otherwise, a tiny word can hide kilobytes and waste CPU. You can find more information about the issue in the Snyk Vulnerability database under SNYK-JS-VALIDATOR-13653476 entry.

The surgical fix: Counting only valid pairs

The change is precise: subtract only base+selector pairs instead of every selector. Old: /(\uFE0F|\uFE0E)/g. New: /[^\uFE0F\uFE0E][\uFE0F\uFE0E]/g. [^…] means “not these,” which forces a preceding non‑selector base. So stray or repeated selectors get counted. This distinction is the key to the fix.

Effective length: str.length — surrogatePairs — basePlusSelectorPairs.

// Padding with stray selectors now fails the max check
const payload = 'test' + '\uFE0F'.repeat(5);
console.log('isLength(payload, { max: 4 }):', isLength(payload, { max: 4 })); // false

// A valid base+selector pair still counts as one perceived char
const basePair = 'A' + '\uFE0F';
console.log('isLength(basePair, { max: 1 }):', isLength(basePair, { max: 1 })); // true

Disclosure and timeline

I followed a responsible disclosure process. I reported the issue, prepared a minimal PoC, and worked with the maintainers on a fix. The maintainers merged the patch, published a release, and then the advisory went live.

I reported the issue along with a proposed fix on October 18, 2025. The maintainers merged a pull request on November 5. Finally, CVE-2025–12758 was published on November 26. More info and links on the GitHub Security Advisory.

Conclusion

The key takeaway remains: Variation Selectors are modifiers, not content. The bug allowed them to be used as invisible padding to bypass max-length checks. After the fix only valid base-and-selector pairs pass the length check. It ensures all stray or repeated selectors are counted toward the actual length.

Please update to validator@13.15.22 or newer. When working with string length, always measure what you are storing, not just what users see.

A Practical Guide to Flutter Accessibility - Part 1: The Basics

Karol Wrótniak — Fri, 07 Nov 2025 12:08:20 +0000

Learn how to build accessible Flutter apps using built-in tools. Fix common issues like screen reader incompatibility, confusing structure, and unclear state changes to create inclusive, user-friendly apps.

Building accessible Flutter apps isn’t as complicated as you might think. Most accessibility problems happen because screen readers can’t understand your controls. Your information structure confuses users. You’re not communicating state changes. This guide will fix these problems using Flutter’s built-in accessibility tools.

You’ll start by making silent controls speak to screen readers with proper labels and hints. Assistive technology users will get the same information as everyone else.

Why this matters to you as a developer

Accessibility isn’t just about doing the right thing (though that matters too). It’s about building better software. When you add proper semantic information to your widgets, you help more than screen reader users. You create clearer code that’s easier to test, debug, and maintain. Many accessibility improvements make the experience better for everyone — better focus management, clearer state communication.

The legal reality

Let’s talk about the elephant in the room: legal requirements. The EU Accessibility Act requires digital services to be accessible by 2025. Fines reach up to 4% of annual revenue for non-compliance. In the US, the ADA doesn’t specify technical standards. Courts reference WCAG guidelines in lawsuits. Companies like Target, Netflix, and Domino’s have faced million-dollar settlements over inaccessible apps. This isn’t some distant possibility — it’s happening right now.

The good news about common problems

The most common Flutter accessibility problems are simple to fix. An IconButton without a label? Silent to screen readers. You’ll fix that using Flutter’s Semantics and MergeSemantics widgets.

The Semantics widget

Think of the Semantics widget as an invisible layer of sticky notes for assistive technology. You wrap your existing UI and provide properties. These describe what the thing is (label, role). They show what it displays (value). They explain what it’ll do (hint). They communicate what state it’s in (flags like selected, hidden, header, button, enabled, liveRegion). You can expose actions (onTap, onLongPress, onScroll) so screen reader users can interact with your interface. You can group multiple visual widgets into a single logical unit.

You won’t use Semantics everywhere — Flutter’s smart about defaults for Material widgets. But you’ll add or override it when something’s silent, chatty, or missing important state information. The goal? Give just enough structured metadata so a user hears “Add to cart, button, selected” instead of a confusing jumble of unrelated text bits.

Giving a voice to silent icons

Here’s our first problem. You’ve got an IconButton that looks fine. For a screen reader, it’s a silent mystery. Wrap it with Semantics and give it a clear label (what it is) and optional hint (what happens when you tap it).

// Without Semantics: announces only "button" because the icon has no text.
IconButton(
  icon: const Icon(Icons.local_drink),
  onPressed: _incrementCounter, // Logs a glass but screen reader doesn't know.
);
// With Semantics: announces "Log water, button" then the hint on explore.
Semantics(
  label: 'Log water',              // What this control represents
  hint: 'Adds one glass to today\'s total', // What happens on activation.
  child: IconButton(
    icon: const Icon(Icons.plus_one),
    onPressed: _incrementCounter,
  ),
);

Keep labels short and specific. Don’t repeat role words like “button” — the system adds that for you. Use value when the visual text alone would be confusing out of context (like an isolated number that means nothing without context).

Understanding other semantic properties

Many other semantic properties solve specific accessibility problems. liveRegion makes dynamic content announce when it changes — perfect for status updates or form validation messages. The isHeader flag tells screen readers that text is a page or section heading. This helps users navigate by jumping between sections. We can’t cover every semantic property in one post. You’ll learn about these and others as we work through real examples. For the complete rundown, check out the official Semantics documentation.

Platform differences to watch

Not all semantic properties work the same way across platforms. Some platforms support certain properties. Others might behave differently. For example, headingLevel only works on Flutter web. Native iOS supports heading levels. Flutter doesn’t wire this through on iOS (there’s an open issue in the Flutter tracker). Android doesn’t even have the concept of heading levels.

Coming from Android development

Do you use Jetpack Compose? Flutter’s Semantics widget works like Compose’s semantics modifier. Both use the same basic idea — wrap UI elements and add metadata like contentDescription (Flutter’s label), role information, and state flags. The main difference is syntax. Flutter uses named parameters in a widget wrapper. Compose uses a modifier with lambda configuration.

Coming from iOS development

SwiftUI’s accessibility system maps to Flutter’s approach. Flutter’s label property is like SwiftUI’s .accessibilityLabel() modifier. hint maps to .accessibilityHint(). State flags like isHeader correspond to .accessibilityAddTraits(.isHeader). All three frameworks — Flutter, Jetpack Compose, and SwiftUI — follow the same core principle: decorate UI elements with semantic metadata. Once you get the concept, switching between platforms becomes easier.

Testing your semantics on device

Let’s see what happens when you run the IconButton example on an Android device with TalkBack enabled. The screen recording below shows the app running on an emulator and the Android Ally plugin in Android Studio. This gives you a real-time control of accessibility settings.

Android emulator with TalkBack and Android Ally plugin.

The double announcement problem

When you swipe through the interface with TalkBack (Android’s built-in screen reader), you’ll notice something weird. Both the Semantics wrapper and the underlying IconButton get announced as separate nodes. TalkBack first reads “Log water, button, Adds one glass to today’s total” from your custom semantics. Then it announces the icon button itself as a separate focusable element.

This creates a confusing experience for screen reader users. They hear the same control twice but with different information. The Android Ally plugin helps you catch these issues. It shows the accessibility tree structure alongside your app. You can grab it from Android Studio’s plugin marketplace to see how assistive technologies interpret your interface.

Using Accessibility Scanner

Google’s Accessibility Scanner app catches this exact problem. The scanner analyzes your app’s interface and flags accessibility issues. It finds duplicate content descriptions, missing labels, and poor contrast ratios. When you run it on our IconButton example, it spots the redundant semantic information. It suggests consolidating everything into a single, clear description.

You can download Accessibility Scanner from the Google Play Store. Run it on your device or emulator. It’s useful during development because it gives you the same feedback that real users with disabilities would get. You don’t have to enable TalkBack yourself.

Testing on iOS

On iOS, Apple’s Accessibility Inspector does the same thing. This built-in developer tool comes with Xcode. It lets you inspect the accessibility tree of your Flutter app running on iOS Simulator or a physical device. When you run the inspector on our problematic IconButton example, it reveals the same issue. You see duplicate semantic nodes that would confuse VoiceOver users.

You can find the Accessibility Inspector in Xcode under Developer Tools. Or launch it from your Applications/Utilities folder if you’ve got Command Line Tools installed. Unlike the Android tools, Accessibility Inspector works with Flutter apps in iOS Simulator. This makes it easy to catch accessibility issues during development without needing a physical device.

Why does this double announcement happen? You wrapped the IconButton without telling Flutter to treat them as a single semantic unit. Let’s fix this by learning how to group related elements.

Fixing double announcements with MergeSemantics

The solution to our double announcement problem is simpler than you might expect. We need to tell Flutter to merge the semantic information from our custom Semantics wrapper with the underlying IconButton. This creates a single focusable element. The MergeSemantics widget does this.

// Fixed: Now announces as a single element.
MergeSemantics(
  child: Semantics(
    label: 'Log a glass of water',     
    hint: 'Adds one glass to today\'s total', 
    child: IconButton(
      icon: const Icon(Icons.plus_one),
      onPressed: _incrementCounter,
    ),
  ),
);

When you wrap multiple widgets with MergeSemantics, Flutter combines all their semantic properties into a single accessibility node. Screen readers now announce “Log a glass of water, button, Adds one glass to today’s total” as one cohesive unit. They don’t treat each wrapper as a separate element.

The MergeSemantics widget is handy when you’ve got compound controls. Think of a button with an icon and text. Or a custom card with multiple interactive elements that should be treated as one logical unit. Without it, screen readers navigate to each semantic layer. This creates confusion for users who expect related elements to be grouped together.

Cross-platform grouping concepts

If you’re working with SwiftUI, this concept maps to the .accessibilityElement(children: .combine) view modifier. This merges accessibility information from child views into a single element. In Jetpack Compose, you get grouping using the mergeDescendants = true parameter in the semantics modifier. All three frameworks recognize that visual hierarchy doesn’t match logical accessibility structure. Multiple UI elements should be announced as one cohesive unit.

Testing the fixed implementation

Now when you test the corrected code with TalkBack or VoiceOver, you’ll hear a single, clear announcement. No more confusing double reading we had before. The screen recording below shows the same setup as earlier. The app runs with both the Android Ally plugin and Accessibility Scanner. This time it displays the clean, merged semantic structure.

MergeSemantics fixing the double announcement issue.

Notice how the accessibility tree now shows just one focusable element instead of those duplicate nodes you saw earlier.

Confirming results on iOS

On iOS, the Accessibility Inspector confirms the same clean result. When you run the corrected MergeSemantics code through Apple’s accessibility tools, the inspector shows a single, merged semantic node. No duplicate announcements or structural issues.

Both TalkBack and the Accessibility Scanner confirm that those redundant announcements are gone. This creates a much better experience for screen reader users.

For more details on semantic grouping options, check out the official MergeSemantics documentation and the broader Semantics class reference. These cover all available properties and grouping strategies.

What you’ve accomplished

You’ve now tackled the most common Flutter accessibility problems using the core toolkit. Silent controls like IconButton now speak with proper labels and hints. Those confusing double announcements? Cleaned up with MergeSemantics. Your app’s semantic structure makes sense to screen readers. You’ve got the tools to test and verify your changes work across both Android and iOS.

These basic semantic properties — solve the vast majority of the accessibility issues you’ll run into in Flutter apps. But there’s more to building inclusive experiences. In Part 2 of this series, you’ll dive into advanced interaction patterns like custom semantic actions for complex gestures.You’ll explore how to handle dynamic content announcements and make custom widgets accessible to assistive technologies.

Originally published at thedroidsonroids.com on November 7, 2025.