Beyond the Prompt: Building Enterprise Solutions with AI & Specification-Driven Design

Overview

Relying on raw prompt engineering or conversational text interfaces alone will not deliver a production-ready, enterprise-grade AI solution. To build resilient, secure, and compliant software in the age of AI assistants, developers must move past chaotic "vibe coding" and adopt a structured, process-oriented architectural workflow.

This session delivers a blueprint for Specification-Driven Design (SDD), demonstrating how disciplined discovery and modular markdown specifications enable a project assistant to successfully manage and execute multiple phases of the software development lifecycle. By treating AI as an execution engine governed by rigorous technical guardrails, rather than a black-box chatbot, engineers can drastically accelerate velocity while maintaining absolute system integrity. We walk through a real-world case study of a decoupled, zero-trust enterprise quality healthcare risk-assessment engine to show this methodology in action.

🚀 Featured Open Source Projects

Explore these curated resources to level up your engineering skills. If you find them helpful, a ⭐️ is much appreciated!

🤖 Artificial Intelligence

Focus: LLM Patterns and Agentic Workflows

🏗️ Data Engineering

Focus: Real-world ETL & MTA Turnstile Data

---

💡 Contribute: Found a bug or have a suggestion? Open an issue and be part of the open source project.

🔗 Related Repository: AI Engineering

Explore the full implementation of the AI specifications and code used in this workflow:
https://github.com/ozkary/ai-engineering

YouTube Video

👍 Subscribe to the channel to get notified on new events!

📅 Agenda

• The Purpose: Understanding the Toolchain & Vibe Coding – Defining the real-world roles of code assistants (like GitHub Copilot and Google Antigravity) and what "vibe coding" actually means for an enterprise workflow.
• The Chaos: The Pitfalls of Planless Execution – The fallout when launching straight into terminal commands without a design baseline: monolithic files, bypassed architectural patterns, and untracked requirements.
• The Discovery & Specification Process: System Decomposition – How to properly break down a complex problem before writing code—identifying distinct system areas, modular boundaries, UI/UX input definitions, core system requirements, and downstream DevOps needs.
• The Blueprint: Establishing Governance & Guardrails – Putting your specifications and governance rules together into a structured, unified layout that forces the AI assistant to strictly follow your target design patterns.
• The Iterative SDLC: Continuous Gap Analysis & Adaptive Specifications – Embracing an Agile approach to handle missing requirements by starting small, continuously feeding refinements to the assistant, and leveraging it to run live gap analyses and solution summaries.

---

The Purpose: Understanding the Toolchain & Vibe Coding

Modern software development has been dramatically reshaped by AI code assistants like GitHub Copilot and Google Antigravity. As developers, these tools offer immense power, but they require a clear understanding of their role in the developer toolchain. Often, developers fall into the trap of "vibe coding"—sitting down in front of an AI chat interface and typing conversational prompts to generate code on the fly without a predefined plan.

While vibe coding is fast and can yield functional prototypes in a couple of hours, it lacks the structure needed for enterprise-grade applications. For enterprise software, we must treat AI assistants not as autonomous magic boxes that build everything, but as peer programmers. They operate best when provided with clear, contextual instructions, and when their scope is constrained to specific, manageable files or tasks.

By integrating these tools into Visual Studio Code or as command-line interfaces (like the Antigravity CLI), we can work side-by-side with the AI. However, this interaction must be deliberate. We must set guardrails so the AI does not scan unrelated files, dilute its focus, or make arbitrary architectural decisions on our behalf.

Chaos vs. AIStorming

The Chaos: The Pitfalls of Planless Execution

What happens when we dive straight into terminal commands or prompt-driven code generation without a design baseline? We enter a state of planless execution, or chaos.

When you prompt an AI to "build a React application with a product form" without constraints:

1. Monolithic Files: The AI tends to generate a single, massive file containing state, logic, rendering, and styles because that is the most direct path to satisfy the prompt.
2. Bypassed Architecture: Common enterprise architectural patterns, such as separating components, containers, and services, are completely ignored.
3. Untracked Requirements & Lost Context: As the chat history grows, the AI starts losing context. Crucial design constraints, accessibility needs, and security protocols are forgotten, forcing the developer to repeatedly restate them.
4. Untraceability: The final codebase becomes difficult to maintain or trace back to original business requirements. There is no documentation or specifications explaining why decisions were made.

To avoid this chaos, we must establish a rigorous design baseline before writing or generating a single line of code.

AI Storming: The Framework for Structured Discovery

To combat the chaos of planless execution, developers must transition from simple vibe coding to a structured methodology known as AI Storming. Similar to traditional brainstorming sessions where developers sketch out designs and architectural workflows, AI Storming leverages the AI assistant as a cognitive partner to explore the domain model, synthesize requirements, and identify hidden edge cases before a single line of application code is written.

By engaging in this process-oriented framework, you use the AI's vast knowledge base to analyze project feasibility, perform system decomposition, and quickly get up to speed on unfamiliar technologies or industry standards. Rather than letting the AI write the application directly from conversational chat, you use the AI to draft the specifications that will ultimately govern the build process.

💡 Learn More: To dive deeper into this methodology, read about the AI Storming Framework.

The Discovery & Specification Process: System Decomposition

Enterprise software development begins with discovery and system decomposition. Instead of executing a "big bang" implementation, we break down a complex problem statement into modular, logical boundaries.

For example, when building a real-world healthcare risk-assessment engine:

1. Identify System Areas: Segment the project into distinct areas such as the database, DevOps pipelines, API endpoints, and the user interface (UI/UX).
2. Define Requirements & Compliance: In healthcare, security, accessibility, and zero-PII (Personally Identifiable Information) compliance are paramount. We must explicitly define these constraints up front.
3. Draft Modular Specifications: Create dedicated markdown specifications for each area (e.g., UI specs, API specs, security specs, database schema specs).

By structuring our discovery process and outputting markdown specifications, we create a clear, traceably documented source of truth. This modular approach ensures that both human developers and AI assistants have a clear boundary of work, preventing scope creep and design drift.

The Blueprint: Establishing Governance & Guardrails

Once the modular specifications are drafted, they are unified into a Solution Blueprint. This blueprint serves as the master driver for the AI assistant.

To enforce guardrails and governance:

1. Specify Coding Standards: Define naming conventions (e.g., PascalCase for React components, camelCase for services), CSS libraries (e.g., Tailwind), and state management patterns.
2. Structure the Project Layout: Define the exact directory structure (e.g., /app for React, /api for Python backend, /assets for media) so the AI knows where to locate and create files.
3. Provide Contextual Libraries: If a library is updated or has specific usage guidelines, write those down or pass the official documentation directly to the AI to prevent it from using outdated code patterns.

By feeding these structured specifications to the AI assistant, we establish governance. The AI is forced to work within our design patterns, ensuring that the generated code is consistent, maintainable, and complies with enterprise standards.

The Iterative SDLC: Continuous Gap Analysis & Adaptive Specifications

Specification-Driven Design is not a static, "one-and-done" process. It is an agile, iterative lifecycle.

1. Start with an MVP: Begin with the minimum viable requirements and a baseline specification.
2. Execute and Review: Let the AI generate code based on the specifications. Run the application, review the code structure, and test the features.
3. Conduct Gap Analysis: As implementation progresses, you will inevitably identify missing requirements (e.g., "How do we handle user authentication on Cloud Run?" or "How do we implement voice-to-text hotkeys for accessibility?").
4. Update the Specs, Not Just the Code: When a gap is found, document the new requirements in the markdown specifications first. Rerun the specs through the AI assistant to let it update the implementation.
5. Traceability & Summaries: Leverage the AI to perform solution summaries and next-step analyses to keep project tracking up-to-date.

This feedback loop ensures absolute traceability. Your documentation and your codebase remain in lockstep, eliminating technical debt and delivering a secure, high-quality, production-ready enterprise solution.

Conclusion

Can we build enterprise-grade, high-quality solutions using generative AI and "vibe coding"? The short answer is yes—but only if we transition from a chaotic conversational interface to a disciplined, process-oriented workflow.

The main highlights of this methodology include:

• Specifications Drive Results: The quality of the AI's output is directly proportional to the structure of the input. Drafting specifications properly is the most effective way to guide an assistant.
• Process Over Chat: Avoid relying on temporary chat windows where context is easily lost. Maintain permanent, adaptive specs in your repository for absolute traceability.
• AI as a Peer Programmer: Treat AI tools as assistants that execute tasks within clear, modular guardrails rather than a magic wand that does the planning for you.
• Continuous Refinement: Embrace the agile loop of gap analysis, updating specifications, and regenerating code to ensure your code and documentation stay aligned.

Ultimately, by learning how to use AI code assistants properly and wrapping them in rigorous technical governance, developers can achieve massive velocity increases without compromising system integrity or security.

---

🌟 Let's Connect & Build Together

Thanks for reading! 😊 If you enjoyed these resources, let's stay in touch! I share deep-dives into AI/ML patterns and host community events here:

• GDG Broward: Join our local dev community for meetups and workshops.
• Global AI Events: Join Global AI Events.
• LinkedIn: Let's connect professionally! I share insights on engineering.
• GitHub: Follow my open-source journey and star the repos you find useful.
• YouTube: Watch step-by-step tutorials on the projects listed above.
• BlueSky / X / Twitter: Daily tech updates and quick engineering tips.

👉 Originally published at ozkary.com

Overview Relying on raw prompt engineering or conversational text interfaces alone will not deliver a production-ready, enterprise-grade A...

Read Article →

AIStorming: A Process-Oriented Framework for AI-Assisted Discovery, Analysis, and Specification

Overview

As the software development lifecycle shifts toward autonomous vibe coding, rapid AI prototyping, and Software Design Description (SDD) driven workflows, engineering teams face a critical structural bottleneck: the discovery and analysis gap. Generative AI tools excel at emitting syntactically valid code, yet they consistently fail when handed vague, ungrounded, or fragmented domain specifications.

To bridge the gap between initial domain exploration and deterministic engineering execution, I introduce AIStorming—a process-oriented framework born out of my engineering practice and foundational work in enterprise data pipelines and cloud-native application architectures.

Throughout my career designing high-scale cloud-native solutions, event-driven microservices, and modern data platforms, domain research, requirement validation, and exploratory design depended heavily on manual web searches, static documentation reviews, and disconnected whiteboarding sessions. Over years of hands-on practice, my workflow naturally evolved from manual research into AI-driven, interactive, and code-centric discovery. By leveraging AI coding assistants directly inside the development workspace to profile sample datasets, stress-test business rules, probe API interfaces, and validate system constraints in real time, I transformed traditional brainstorming into an active, deterministic engineering phase: AIStorming.

AIStorming formalizes the process of using AI coding tools (e.g., GitHub Copilot, Google Antigravity) to conduct real-time domain discovery, exploratory analysis, and system boundary mapping across both cloud-native software and data engineering domains. Rather than relying on abstract, non-executable IT discovery frameworks, AIStorming anchors domain analysis directly in executable code, version control, and data validation. This yields structured problem statements, refined use cases, quantifiable technical requirements, and machine-readable specifications optimized for vibe coding, cloud-native design, and automated SDD execution.

---

🚀 Featured Open Source Projects

Explore these curated resources to level up your engineering skills. If you find them helpful, a ⭐️ is much appreciated!

🏗️ Data Engineering

Focus: Real-world ETL & MTA Turnstile Data

🤖 Artificial Intelligence

Focus: LLM Patterns and Agentic Workflows

📉 Machine Learning

Focus: Introduction to machine learning

---

💡 Contribute: Found a bug or have a suggestion? Open an issue! and be part of the open source project.

---

1. The Core Engineering Challenge: The Discovery-to-Implementation Gap

In traditional enterprise software engineering, product discovery is often disconnected from actual system implementation. Product managers, business analysts, and architects spend weeks producing static requirements documents, wireframes, or text-heavy stories. When these artifacts are passed down to software engineers—or fed as prompt context into AI coding tools—the implementation breaks down due to implicit assumptions, unverified data schemas, unexpected edge cases, and missing operational constraints.

In an era dominated by AI-assisted synthesis, garbage context in results in garbage execution out.

+-----------------------------------------------------------------------------------+
|                            TRADITIONAL DISCOVERY GAP                              |
|                                                                                   |
|  [ Domain & Business ] ---> ( Static Docs / Whiteboards ) ---> [ AI Assistant ]   |
|  Ideation & Concepts          Unverified Context                 Hallucinated     |
|                                                                  Implementation   |
+-----------------------------------------------------------------------------------+
                                        VS.
+-----------------------------------------------------------------------------------+
|                             AISTORMING FRAMEWORK                                  |
|                                                                                   |
|  [ Domain Input ]  ---> { AIStorming: Code-Centric Analysis } ---> [ SDD & Vibe ] |
|  Raw Data / Rules /     Exploratory Scripts, Profiling,         Deterministic     |
|  API Contracts          & Requirement Synthesis in IDE             Builds         |
+-----------------------------------------------------------------------------------+

To leverage AI coding assistants safely and at enterprise quality, the Discovery Phase must be reinvented. It can no longer be a passive ideation exercise; it must become an active, code-centric discovery engine that validates domain facts, data structures, and service behaviors before full-scale software architecture and implementation begin.

---

2. What is AIStorming?

AIStorming is the process-oriented methodology of conducting domain discovery, exploratory data/logic analysis, and system boundary definition by pairing human engineering expertise with AI coding tools inside an Integrated Development Environment (IDE).

The objective of AIStorming is not to generate production application code or deploy live systems immediately. Instead, its primary output is a structured set of verified, code-grounded engineering artifacts:

1. Grounded Problem Statements: Unambiguous scope boundaries, operational objectives, and domain invariants.
2. Exploratory Data & Logic Findings: Code-verified insights into payload structures, edge cases, integration contracts, API behaviors, and processing constraints.
3. Formal Functional & Technical Requirements: Explicit inputs, state behaviors, domain events, security boundaries, and non-functional targets (throughput, latency, reliability).
4. Machine-Readable Specifications (SDD): Domain models, schemas, contract interfaces, and prompt-context files tailored for downstream vibe coding, agentic orchestration, and automated pipeline execution.

---

3. Foundational Principles of AIStorming

Derived from the universal tenets of my Data Engineering Process Fundamentals (DEP) and expanded across cloud-native software architecture, AIStorming adapts proven discovery mechanics to AI-driven developer tooling.

I. The Code-Centric Paradigm

Traditional discovery relies on prose descriptions that fail upon first contact with compiler logic, schema validation, or streaming engines. AIStorming dictates that discovery must be code-centric from day one.

• Exploratory data analysis (EDA), API probing, schema validation, and domain logic simulations are written as executable scripts (Python, TypeScript, SQL, Go, Jupyter Notebooks) inside the IDE workspace.
• AI tools are forced to interact with concrete execution outputs, stack traces, and SDK responses rather than abstract concepts.

II. Dataset & Domain Grounding

AI models hallucinate when operating in an isolated context vacuum. AIStorming requires immediate grounding against real-world sample datasets, schema definitions, domain models, and API interfaces.

• Evaluates data quality, structural variance, integration frequencies (batch vs. streaming event-driven), and service boundaries.
• Uses AI assistants to parse, profile, and transform sample payloads and domain entities live during the discovery window.

III. Source Control and Auditable Iteration

Prompt histories floating in web interfaces are disposable, non-reproducible, and unmaintainable. AIStorming enforces that every discovery artifact—exploratory notebooks, schema models, interface definitions, and context files—is checked directly into a Git repository (e.g., GitHub).

• Enables collaboration between software engineers, data architects, and AI agents.
• Maintains a versioned, auditable history of how business domain rules evolved into formal technical specifications.

IV. Bridge to Vibe Coding and SDD

AIStorming serves as the explicit precursor to Vibe Coding (rapid, intent-driven application development using AI models) and Software Design Description (SDD) generation. By translating loose ideas into code-verified constraints during AIStorming, downstream AI models receive high-fidelity, hallucination-free prompts during full-scale development.

---

4. The 4 Universal Steps of the AIStorming Process

Whether applied to cloud-native microservices, event-driven streaming applications, serverless architectures, or modern enterprise data platforms, the AIStorming framework executes across four process-oriented phases.

+-------------------+      +-------------------+      +-------------------+      +-------------------+
|  STEP 1:          | ---> |  STEP 2:          | ---> |  STEP 3:          | ---> |  STEP 4:          |
|  Problem          |      |  Exploratory      |      |  Use Case &       |      |  SDD & Vibe       |
|  Framing &        |      |  Data & Domain    |      |  Requirement      |      |  Specification    |
|  Context Prime    |      |  Analysis         |      |  Synthesis        |      |  Output           |
+-------------------+      +-------------------+      +-------------------+      +-------------------+

Step 1: Problem Framing & Context Priming

• Objective: Establish domain boundaries and prime the AI workspace with domain context.
• Process:
  1. Initialize a dedicated discovery branch in the code repository.
  2. Create a core workspace context file (CONTEXT.md or system prompt boundaries) containing raw business objectives, domain rules, SLA requirements, and target application guidelines.
  3. Engage the AI coding assistant to challenge the problem scope, identifying missing assumptions, unstated edge cases, or domain contradictions.

Step 2: Exploratory Data & Domain Logic Analysis

• Objective: Verify domain facts and data behaviors using runnable code inside the IDE.
• Process:
  1. Load representative data samples, schema models, domain event payloads, or third-party API contracts into VS Code or Jupyter Notebooks.
  2. Pair with the AI assistant to write exploratory scripts using standard manipulation libraries, data frames, or contract interfaces (Pandas, Pydantic, Zod, Spark/PySpark, SQL).
  3. Perform data profiling, test payload transformations, inspect edge cases, validate event structures, and evaluate performance/throughput assumptions.
  4. Commit all exploratory scripts, test executions, and output traces to Git.

Step 3: Use Case & Requirement Synthesis

• Objective: Extract structured engineering requirements from discovery findings.
• Process:
  1. Prompt the AI assistant to analyze the commit history, exploratory scripts, and execution outputs generated in Step 2.
  2. Synthesize findings into formalized Use Cases (actor/system interactions, event triggers, preconditions, happy path flows, failover behaviors).
  3. Categorize non-negotiable Technical Requirements:
     • Data Integration & Schema Transformation rules
     • Cloud-Native Application Patterns (Event-driven, REST/GraphQL APIs, Pub/Sub boundaries)
     • Performance, Scalability & Latency SLA targets
     • Security, Identity, Governance, and Compliance boundaries

Step 4: SDD & Vibe Coding Specification Output

• Objective: Produce machine-readable software specifications for autonomous AI execution.
• Process:
  1. Compile discovery outputs into a standardized Software Design Description (SPEC.md / ARCHITECTURE.md).
  2. Generate baseline interface contracts, schemas, and domain types (TypeScript interfaces, OpenAPI specs, Pydantic data models, Avro/Protobuf schemas, ERD models).
  3. Define precise context prompts and agent instructions to drive subsequent implementation phases (Vibe Coding, Automated Test Generation, and CI/CD development).

---

5. Architectural Deliverables Matrix

To maintain enterprise quality, an AIStorming session must terminate in a concrete set of repository artifacts:

Deliverable Phase	File Artifact	Content & Purpose	Target Consumer
Problem Definition	PROBLEM.md	Domain boundaries, business goals, explicit out-of-scope declarations	Lead Engineers & Architects
Exploratory Analysis	analysis/*.ipynb, scripts/*	Executable data profiling, edge-case tests, API contract probes	Engineering Team & AI Agents
Use Cases	USE_CASES.md	System interactions, domain event triggers, failure modes, retry logic	Product Owners & Testing Engines
Technical Specs	REQUIREMENTS.md, SPEC.md	Data models, storage schemas, security boundaries, SLA performance targets	Vibe Coding AI Tools (Cursor, Copilot, Claude)
Architecture Contract	ARCHITECTURE.md, schemas/*	System topology, ERD models, OpenAPI/AsyncAPI specs, CI/CD pipeline rules	SDD Generators & Developers

---

6. Practical Application: Enterprise Cloud-Native & Data Platform Build

To demonstrate the versatility of AIStorming across cloud-native microservices and high-scale data platforms, consider the execution path of a modern enterprise solution:

1. The Human Intent: An architect needs to design a high-throughput, event-driven data ingestion platform that processes live streaming payloads into an analytical data lake.
2. The AIStorming Phase:
   • Instead of asking an AI tool to "write a real-time data ingestion application," the team opens the IDE and loads representative stream logs and target schemas.
   • The architect uses AIStorming to draft and run exploratory Python/PySpark scripts inside the IDE, testing deserialization speed, schema drift, and payload validation rules.
   • The AI assistant identifies that 6% of incoming event payloads contain missing nested timestamp attributes and schema variations that would break downstream parquet writes.
3. Requirement Synthesis: The team updates REQUIREMENTS.md via AIStorming to explicitly mandate upstream payload sanitization, dead-letter routing (DLQ), and a strict contract enforcement layer.
4. SDD & Vibe Implementation: The resulting SPEC.md, Pydantic models, and OpenAPI/AsyncAPI specs are fed into coding agents. The agents write production-grade microservices and pipeline code on the first pass because the domain edge cases were caught during AIStorming.

---

7. Conclusion: AIStorming as an Enterprise Engineering Standard

As artificial intelligence shifts software and data engineering from manual syntax writing to high-level system orchestration, the role of the engineer evolves from code writer to system architect and discovery strategist.

AIStorming bridges the foundational gap between raw domain ideas and deterministic execution. By marrying the process-oriented discipline of Data Engineering Process Fundamentals with cloud-native software architecture patterns and modern AI coding tools, AIStorming transforms discovery from a passive, unverified discussion into a repeatable, code-centric, and auditable engineering standard.

By adopting AIStorming as a formal phase prior to vibe coding and SDD execution, engineering organizations can eliminate AI hallucination risks, enforce enterprise domain integrity, and accelerate software delivery with complete architectural control.

---

References & Foundational Frameworks

• Garcia, Oscar D. (Ozkary). "From Raw Data to Roadmap: The Discovery Phase in Data Engineering Process Fundamentals." Ozkary Technologies
• Garcia, Oscar D. (Ozkary). "Data Engineering Process Fundamentals - Design and Planning."
• Garcia, Oscar D. (Ozkary). "Architecting an Agentic Data Pipeline - From Data Lake Discovery to Managed Orchestration."

---

🌟 Let's Connect & Build Together

Thanks for reading! 😊 If you enjoyed these resources, let's stay in touch! I share deep-dives into AI/ML patterns and host community events here:

• GDG Broward: Join our local dev community for meetups and workshops.
• Global AI Events: Join Global AI Events.
• LinkedIn: Let's connect professionally! I share insights on engineering.
• GitHub: Follow my open-source journey and star the repos you find useful.
• YouTube: Watch step-by-step tutorials on the projects listed above.
• BlueSky / X / Twitter: Daily tech updates and quick engineering tips.

👉 *Originally published at ozkary.com*

Overview As the software development lifecycle shifts toward autonomous vibe coding , rapid AI prototyping, and Software Design Descriptio...

Read Article →

Building Reusable & Extendable Agents with the Google ADK

Overview

The goal of this presentation is to introduce the audience to an agentic SDK—specifically the Google Agent Development Kit (ADK), while addressing a critical trap in modern AI engineering. It is incredibly easy to fall into the habit of building AI agents using basic procedural code or siloed Jupyter Notebooks. While these approaches work for initial validation, they fail to scale in an enterprise environment.

Instead, this session demonstrates how to leverage robust software design patterns and foundational architectural principles. By building an abstraction layer over the SDK, we can create a mature, enterprise-ready library. This approach allows us to decouple our core business logic from third-party frameworks, making our codebase completely agnostic to any single SDK and giving us the flexibility to swap underlying tools as the AI ecosystem evolves.

Follow the next sections for the main points of the presentation, and then take a look at the video presentation to dive deeper into the concepts.

Building Reusable & Extendable Agents with the Google ADK

Presentation Summary

Discover how to transition from building monolithic, single-prompt chatbots to designing highly modular, scalable, and extendable enterprise agents using the Google Agent Development Kit (ADK). This presentation provides a hands-on architectural deep dive into building process-oriented workflows, implementing the Model Context Protocol (MCP) for cloud data platform integrations, and utilizing automated DevOps tooling to eliminate technical debt in your AI engineering pipelines.

The Monolithic Prompt & SDK Trap

When developers start building AI agents, the initial momentum is almost always driven by quick prototyping. You pull down a hot new SDK, run a quick pip install, and start hardcoding prompts directly into your files.

While this works for a weekend hobby project, it quickly collapses under its own weight in an enterprise ecosystem. You end up with multiple developers writing siloed, inconsistent code, duplicating core tasks like error handling, and introducing massive technical debt. Even worse, your entire system becomes tightly coupled to a single third-party framework. If you ever need to pivot or replace that framework, you are looking at a complete rewrite.

Production-grade engineering requires moving away from spaghetti code toward process-oriented, SDK-agnostic architecture.

Architectural Blueprint: Layered Agent Design

To achieve true reusability and governance, we must build a core architectural foundation that abstracts third-party dependencies away. Instead of letting an external SDK dictate our application structure, we stack agents in specialized layers via inheritance.

Building Reusable & Extendable Agents with the Google ADK - Architecture

1. The Base Agent (The Foundation)

The BaseAgent is an abstract base class responsible for handling cross-cutting concerns that every enterprise agent needs:

• Consistent logging structures.
• Centralized security and exception handling.
• Standardized interface definitions.

By encapsulating these inside a base layer, any new agent you spin up automatically inherits these core enterprise features.

2. The Basic Agent (Configuration over Hardcoding)

The BasicAgent extends the base layer to introduce configuration management. To keep our code robust and maintainable, prompts should never be hardcoded.

Instead, the BasicAgent pulls details—like the target Gemini model or project IDs—from environment variables. Simple instruction hooks can be fed via configurations, allowing your DevOps pipeline to deploy behavior updates or model rollouts without requiring a single line of code to change.

3. The Tool Agent (Advanced Governance & MCP)

The ToolAgent introduces external capabilities through the Model Context Protocol (MCP). For complex enterprise needs, configuration files aren’t enough. The ToolAgent uses file pointers to read advanced Markdown documents detailing strict system instructions, safety limitations, data boundaries, and governance rules.

Extending Capability with Custom & Native MCP Tools

An agent on its own is just an engine that knows how to talk to a Large Language Model. To make it useful, it needs a way to interact with the outside world. This presentation highlighted two separate paradigms for handling tools:

Abstracting Built-in SDK Tools

The Google ADK provides out-of-the-box tools for major platforms like BigQuery. However, to maintain code isolation, we shouldn’t map those tools blindly. In the demo code, we extended the native tool using a custom authorization class (AuthorizationContext). This separation of concerns ensures that token generation, credential refreshing, and cloud authentication happen entirely independent of the agent’s reasoning loop.

Building Custom MCP Tools from Scratch

When an SDK lacks a tool for your specific business requirements—such as interacting with a custom file bucket or specific database—you can build your own using frameworks like FastMCP. The presentation demonstrated a custom Google Cloud Storage (GCS) tool capable of:

• Listing target bucket contents.
• Generating compressed file previews.
• Executing self-diagnostic checks to validate connections before a workflow begins.

The Unsung Hero: The Agent Runner Runtime

One of the least understood components of agentic design is the Agent Runner. While the Google ADK provides an excellent local web-based playground that automatically bootstraps your environment for rapid testing, production environments require you to explicitly script this runtime pipeline.

The Agent Runner acts as the orchestrator of your system, managing three vital elements:

• Orchestration: Connecting multi-agent workflows (e.g., passing tasks seamlessly between a storage agent and a BigQuery data agent).
• Session Management: Directing the active state of an execution path.
• Memory Management: Maintaining persistence. While short-term tasks can run on fast, volatile in-memory sessions, complex industrial or manufacturing pipelines require long-term history to monitor trends, catch system drift, and diagnose process failures over time. The presentation demonstrated wiring an isolated SQLite engine into the runner to handle this tracking cleanly.

Modern DevOps for AI: UV and Makefiles

Enterprise code demands automated quality gates. Rather than relying on standard global package structures, the project repository leverages modern Python tooling to accelerate developer onboarding:

• UV (Virtual Environment Manager): A lightning-fast, modern alternative to legacy virtualenv tools. Using a strict uv.lock file ensures every developer on your team runs identical dependency versions, entirely eradicating the “it works on my machine” problem.

• Makefiles as CI/CD Blueprints: Instead of manually typing tedious execution commands, a standard Makefile orchestrates development tasks. Running make lint catches configuration errors and unmapped dependencies (like an imported but unused session config) before the code ever reaches a code review, while commands like make run-tool smoothly handle localized testing.

Key Takeaways for Enterprise Developers

• Isolate the SDK: Treat third-party agent frameworks as pluggable libraries, not foundational pillars. Abstract them behind abstract base classes so you can swap architectures with minimal friction.
• Configuration Wins Over Code: Keep your agent identities, target models, and governance logic inside Markdown and environment variables. Let your DevOps pipelines drive system behavior.
• Rely on Runtimes for Memory: Keep your agents lean. Let specialized agent runners handle the operational state, session history, and database logging.

Resources & Next Steps

• Get the Code: Explore the foundational structures, base classes, and custom MCP tool definitions by visiting the official GitHub Repository. (Don’t forget to star the repo if you find the patterns helpful!)

• Dive Deeper into Engineering Processes: For a comprehensive guide on building scalable, process-oriented architectural systems, check out my book, “Data Engineering Process Fundamentals”.

🤖 Artificial Intelligence

Focus: LLM Patterns and Agentic Workflows

🚀 Featured Open Source Projects

Explore these curated resources to level up your engineering skills. If you find them helpful, a ⭐️ is much appreciated!

🏗️ Data Engineering

Focus: Real-world ETL & MTA Turnstile Data

📉 Machine Learning

Focus: MLOps and Productionizing Models

💡 Contribute: Found a bug or have a suggestion? Open an issue! and be part of the open source project.

YouTube Video

Take a look at this video and learn about building and testing agents using the Google Agent Development Kit (ADK) by leveraging its CLI and web tool. We’ll start from the absolute basics, learning how to build a simple agent and test it instantly.

From there, we will move on to extend our agents by building custom Model Context Protocol (MCP) tools. Throughout this session, we will focus on staying away from hardcoded prompts. Instead, you’ll learn how to leverage clean software design patterns to build truly reusable, extendable agents that can adapt dynamically with the use of configurable prompts and plug-and-play MCP tools, shifting your development loop from a one-off script or simple notebook into a scalable, production library.

👍 Subscribe to the channel to get notify on new events!

🌟 Let’s Connect & Build Together

Thanks for reading! 😊 If you enjoyed these resources, let’s stay in touch! I share deep-dives into AI/ML patterns and host community events here:

• GDG Broward: Join our local dev community for meetups and workshops.
• Global AI Events: Join Global AI Events.
• LinkedIn: Let’s connect professionally! I share insights on engineering.
• GitHub: Follow my open-source journey and star the repos you find useful.
• YouTube: Watch step-by-step tutorials on the projects listed above.
• BlueSky / X / Twitter: Daily tech updates and quick engineering tips.

👉 Originally published at ozkary.com

Overview The goal of this presentation is to introduce the audience to an agentic SDK—specifically the Google Agent Development Kit (ADK), ...

Read Article →

From Passive Dashboards to Active Agents: Real-Time Reasoning over Data Streams

Overview

Dashboards are effective at showing us that something is breaking, but they usually rely on a human to watch the screen and decide what to do next. In this session, we will look at how to take a standard real-time telemetry dashboard and make it autonomous.

We will walk through a practical implementation using an Angular frontend and a Node.js server. We’ll look at how the system leverages a relational database for persistence and a Redis in-memory cache to handle high-frequency and short volume data feeds. From there, we incorporate an AI Agent that follows three core principles: perceiving the data stream through a sliding window, reasoning against statistical control limits, and acting by sending real-time analysis back to the user. This session is focused on bridging the gap between raw data streams and automated decision-making.

From Passive Dashboards to Active Agents: Real-Time Reasoning over Data Streams

🚀 Featured Open Source Projects

Explore these curated resources to level up your engineering skills. If you find them helpful, a ⭐️ is much appreciated!

🏗️ Data Engineering

Focus: Real-world ETL & MTA Turnstile Data

🤖 Artificial Intelligence

Focus: LLM Patterns and Agentic Workflows

📉 Machine Learning

Focus: Introduction to machine learning

💡 Contribute: Found a bug or have a suggestion? Open an issue! and be part of the open source project.

🔗 Review the repo used for this presentation:

Tech Stack

YouTube Video

👍 Subscribe to the channel to get notify on new events!

📅 Agenda

• The Real-Time Feed: Monitoring Device Telemetry

An introduction to the live system where devices emit high-frequency data for quality monitoring and 3-sigma control limit oversight.

• System Architecture: From Ingestion to Persistence

A deep dive into the technical stack, mapping out the data journey through Node.js, Redis in-memory caching, and relational database storage.

• The Human in the Loop: Cognitive Limitations

Exploring the “Passive Monitoring” challenge—why relying on human interpretation of real-time alerts creates a bottleneck in process control.

• The AI Agent: Applying the 3 Principles

Implementing the “Active Observer” using the three core pillars of AI Agents: Perception (the window), Reasoning (the limits), and Action (the analysis).

• The Intelligent Journey: Summary & Advantages

Recapping our transition from a passive monitor to a smart system and discussing the advantages of automated, agentic data interpretation.

⭐ Why Attend?

The industry is moving beyond simple “Chat” interfaces and into the realm of Agentic Observability. By attending this session, you will see a practical blueprint for integrating intelligence directly into a high-velocity data stack.

👥 Who Is This For?

• Junior Developers: Learn the fundamentals of real-time streaming, how to manage state in Node.js, and how to interact with AI APIs in a professional environment.
• Senior Engineers & Architects: See a robust architectural pattern for integrating Redis, relational databases, and AI Agents while maintaining system stability and security.
• Decision Makers (VPs/Directors): Understand the ROI of “Active Monitoring”—how AI Agents can act as a force multiplier for your engineering teams by automating the first layer of data interpretation.
• Quality & Reliability Engineers: Explore how to digitize the control limit logic you already use into an autonomous 24/7 “Digital Twin.”

Presentation

The Real-Time Feed Challenge

High-velocity telemetry defines the “digital pulse” of modern industrial systems.

• Telemetry Streams: Industrial devices emit continuous telemetry (Temperature, Sound, Humidity). These data points require sub-second processing to maintain operational stability.
• Control Limits: Quality engineers rely on statistical boundaries to define “normal” operation. Detecting drift is the critical first step in identifying risks before failure occurs.

Scalable System Architecture

A multi-layered stack designed to bridge the gap between ingestion and intelligence.

• Redis Cache: Manages the “Live State” or Digital Twin. Provides sub-millisecond access for immediate AI perception.
• Relational Data Warehouse: Powers the historical persistence layer for long-term trend analysis and compliance auditing.
• Node Controller: The orchestration hub. Manages telemetry ingestion, state updates, and the execution of the agentic reasoning loop.

The “Human in the Loop” Trap

Passive observability relies on human interpretation, creating a critical bottleneck.

• Cognitive Overload: Humans struggle to interpret hundreds of concurrent streams, missing subtle patterns.
• Alert Fatigue: Constant threshold violations desensitize responders, causing critical 3σ violations to be ignored.
• Response Latency: The time required for a human to interpret a dashboard often exceeds the window for effective corrective action.

The 3 Principles of AI Agents

Automating observability requires a system that can perceive, reason, and act independently.

1. Perception: Maintaining a stateful sliding window of the Digital Twin to understand temporal context.
2. Reasoning: Evaluating the stream against statistical 3σ limits and physical engineering constraints.
3. Action: Closing the loop by emitting real-time narratives or triggering autonomous safety protocols.

The Intelligent Journey: Comparison

Feature	Passive Monitor	Smart Monitor
Interpretation	Requires human "eyes-on-glass"	Autonomous, semantic interpretation
Response	Reactive to simple thresholds	Proactive identification of drift
Reliability	High risk of missed signals	Intelligent filtering of noise
Data Context	Disconnected historical vs. live	Stateful perception of "Live Device"
Intervention	Significant human latency	Automated safety & audit narratives

🌟 Let’s Connect & Build Together

Thanks for reading! 😊 If you enjoyed these resources, let’s stay in touch! I share deep-dives into AI/ML patterns and host community events here:

• GDG Broward: Join our local dev community for meetups and workshops.
• Global AI Events: Join Global AI Events.
• LinkedIn: Let’s connect professionally! I share insights on engineering.
• GitHub: Follow my open-source journey and star the repos you find useful.
• YouTube: Watch step-by-step tutorials on the projects listed above.
• BlueSky / X / Twitter: Daily tech updates and quick engineering tips.

👉 Originally published at ozkary.com

Overview Dashboards are effective at showing us that something is breaking, but they usually rely on a human to watch the screen and decide...

Read Article →

Architecting an Agentic Data Pipeline - From Data Lake Discovery to Managed Orchestration

Overview

This session explores the strategy of leveraging AI to move beyond manual implementation and into the next level of data engineering. We dive into a process that positions the AI not as a syntax generator, but as a cognitive partner in the engineering lifecycle. We will examine the architectural shift required to transform raw data lake assets into high-performance, orchestrated systems, focusing on the strategic collaboration between human intent and agentic design.

🚀 Featured Open Source Projects

Explore these curated resources to level up your engineering skills. If you find them helpful, a ⭐️ is much appreciated!

🏗️ Data Engineering

Focus: Real-world ETL & MTA Turnstile Data

🤖 Artificial Intelligence

Focus: LLM Patterns and Agentic Workflows

📉 Machine Learning

Focus: MLOps and Productionizing Models

---

💡 Contribute: Found a bug or have a suggestion? Open an issue! and be part of the open source project.

🔗 Related Repository: AI Agents for Data Engineering

Explore the full implementation of the AI Agents used in this workflow:
https://github.com/ozkary/data-engineering-mta-turnstile/tree/main/ai-agents

YouTube Video

👍 Subscribe to the channel to get notify on new events!

📅 Agenda

• Data Lake Discovery: The strategy of deploying discovery agents to autonomously identify patterns and define the foundation of the data grain.
• Governance & Requirements: Establishing the strategic guardrails and requirements that empower an "Architect" agent to maintain system consistency.
• Logical Design for the Staging Area: A process dive into using AI to propose and build a logical abstraction layer, separating raw sources from core business logic.
• Designing and Implementing the Physical Model: How agents navigate the transition to physical storage, building Dimension and Fact tables while maintaining referential integrity.
• Incremental Update Strategy: Developing a sustainable approach to support continuous data feeds from the data lake using idempotent, self-healing processes.
• Pipeline Design and Orchestration: The coordination of complex tasks to manage the relationship between dimensions and facts, ensuring strict lineage and integrated observability.

⭐ Why Attend?

• Elevate Your Role: Learn how to shift your focus from writing repetitive code to defining high-level architectural intent and performing strategic design reviews.
• Master Systemic Reasoning: Understand how to leverage AI to solve complex engineering challenges like referential integrity and dependency management at scale.
• Build for Operations: Move toward a model where system health and observability are built-in byproducts of the design process, not afterthoughts.

👥 Who Is This For?

• Data Engineers & Architects: Looking to evolve their workflow from manual scripting to high-level systemic design.
• Engineering Leaders: Interested in the ROI and reliability of integrating autonomous agents into the development lifecycle.
• AI Enthusiasts: Wanting to see a practical, "beyond-the-chatbot" application of agentic reasoning in a production environment.
• Technical Decision Makers: Seeking a strategy for maintaining governance and referential integrity in an AI-augmented organization.

Presentation

Automating the Data Engineering Lifecycle

We are running a modern Data Engineering process by combining the reasoning power of AI Agents with the standardized connectivity of MCP tools.

• Goal: Move from manual scripting to an intelligent, agent-led pipeline.
• Outcome: A system that can discover, map, and orchestrate data across the cloud.

How do we leverage these tools?

The "Brains" and the "Hands" of the process.

• AI Agents: Use Large Language Models (LLMs) to understand complex system instructions and specific user prompts. They provide the "logic" behind the process.
• MCP Tools: Provide the "connectivity." They expose metadata to the agent, which allows the AI to understand exactly what actions are available and how to execute them correctly.

How does this all work?

The Execution Loop

• The Model: The agent calls a managed LLM service in the cloud (Gemini) for high-level reasoning.
• Discovery: The agent "sees" the available MCP tools and automatically understands how to use them to interact with GCS or BigQuery.
• Governance: System Prompts provide the guardrails, core requirements, and engineering standards the agent must follow.
• Action: The User Prompt provides the specific task (e.g., "Find today's files"). The agent then executes the work.

Intelligent Orchestration

We build an AI-powered Data Engineering process that successfully handles:

• Data Lake Discovery: Automatically identifying patterns and namespaces in GCS.
• Data Warehouse Orchestration: Mapping those discoveries directly into BigQuery and creating the data models for analysis.

AI-Driven Data Engineering

• Agents can connect to a data lake and run discovery on the file
• Agents can use the result of the discovery to build external tables, views, tables and even stored procedures for the incremental update process

🌟 Let's Connect & Build Together

Thanks for reading! 😊 If you enjoyed these resources, let's stay in touch! I share deep-dives into AI/ML patterns and host community events here:

• GDG Broward: Join our local dev community for meetups and workshops.
• Global AI Events: Join Global AI Events.
• LinkedIn: Let's connect professionally! I share insights on engineering.
• GitHub: Follow my open-source journey and star the repos you find useful.
• YouTube: Watch step-by-step tutorials on the projects listed above.
• BlueSky / X / Twitter: Daily tech updates and quick engineering tips.

👉 Originally published at ozkary.com

Overview This session explores the strategy of leveraging AI to move beyond manual implementation and into the next level of data engineer...

Read Article →

AI Driven App Architecture - Smart Development Life Cycle Governance

Overview

As development teams scale, maintaining architectural consistency becomes the biggest bottleneck. Documents are ignored, and linters only catch syntax errors, not design patterns.

In this session, we will demonstrate how to transform AI from a passive coding assistant into an active Architectural Enforcer. By embedding your "unwritten rules" directly into the repository configuration, you create a developer experience where the AI enforces your patterns in real-time.

We will explore how this shifts the workflow: new developers are guided by the AI from day one, preventing architectural leakage before a pull request is ever opened.

🚀 Featured Open Source Projects

Explore these curated resources to level up your engineering skills. If you find them helpful, a ⭐️ is much appreciated!

🏗️ Data Engineering

Focus: Real-world ETL & MTA Turnstile Data

🤖 Artificial Intelligence

Focus: LLM Patterns and Agentic Workflows

📉 Machine Learning

Focus: MLOps and Productionizing Models

---

💡 Contribute: Found a bug or have a suggestion? Open an issue! and be part of the open source project.

YouTube Video

👍 Subscribe to the channel to get notify on new events!

Video Agenda

The Problem: Architectural Drift

Why strict rules (Controller-View, Pascal/camelCase) degrade over time and how AI can fix it.

The Intelligence Engine

Breakdown of the core components: Global Rules, Contextual Guardrails, Agent Tools, and Directory Structure.

Configuration: Global Governance

Setting up global "system prompts" for the repository to enforce tech stack and naming conventions.

Configuration: Contextual Guardrails

Creating "firewalls" for specific folders (e.g., preventing logic in views, preventing API calls in Controllers).

Configuration: The Tooling

Building custom Slash Commands (/new-module) to automate "Vertical Slice" scaffolding.

Configuration: The Auditor Agent

Implementing a specialized "Gatekeeper" persona that scans imports to ensure strict layer separation.

Agent Mapping

A conceptual framework comparing repository configuration to autonomous agent architecture.

💡 Why Attend?

• Stop writing boilerplate: Learn to automate complex folder structures with one command.
• Reduce PR Reviews: Shift governance "left" by having the AI catch architectural errors instantly.
• Interactive Demo: See the .github configuration in action on a real codebase.
• Takeaway Code: Leave with the copy-paste markdown templates to implement this in your own repo tomorrow.

Target Audience

• Tech Leads & Architects who need to enforce standards across scaling teams.
• Developers who are tired of correcting the same patterns in code reviews.
• DevOps Engineers interested in "Governance as Code."
• Leadership teams that are trying to raise standards and productivity in their organizations.

Presentation

SETTING THE STAGE

The Context

• We enforce a strict pattern using the ViCSA architecture
• PascalCase for UI Components.
• camelCase for Logic & Services.
• Separation of Concerns (SoC) is non-negotiable.

The Problem

• Architectural Drift: Patterns degrade over time.
• Passive Docs: Wiki pages are ignored.
• Linter Limits: Linters catch syntax, not architecture.
• Solution: Active Governance via AI.

THE INTELLIGENCE ENGINE

Core AI Policies

• Centralized Config: Rules live in the repo, not the user's IDE.
• Global Rules: Applied to every interaction (System Prompt).
• Contextual Rules: Triggered only when specific files are opened.
• Agent Tools: Custom commands to scaffold new components, controllers or services.

CONFIGURATION: GLOBAL GOVERNANCE

Global Instructions

File: .github/copilot-instructions.md

This acts as the System Prompt for the entire repository. It is silently added to every interaction.

• Tech Stack: TS, Tailwind, Hooks.
• Naming: Pascal vs camelCase.
• Flow: View → Controller → Service -> API.

DEV EXPERIENCE: THE SILENT ENFORCER

Without Config

A developer asks:

How do I create a new service?

• AI suggests a generic Class-based service.
• Suggests creating a utils.js file.
• Ignores project folder structure.

With Config

A developer asks: How do I create a new service?"

• AI reads the Governance.
• Response: Create src/services/userAuth/index.ts using a functional export, as per project standards.

CONFIGURATION: CONTEXTUAL GUARDRAILS

View Layer Rules

File: .github/instructions/controller-layer.md

Trigger: Opening any **/*.tsx file.

• "You are a View."
• "No Logic allowed."
• "No direct API calls."

Controller Layer Rules

File: .github/instructions/view-layer.md

Trigger: Opening any **/controller.ts file.

• "You are a Controller."
• "Use Services, NOT Fetch."
• "Manage State here."

DEV EXPERIENCE: REAL-TIME INTERVENTION

The Scenario

• A developer tries to write fetch() inside a UI Component (index.tsx).
• They ask Copilot: "Write a fetch call here for me."

The Intervention

Ghost Text: Copilot refuses to autocomplete the network call.

Chat Reply:

I cannot. This is a View file. Please move this logic to the sibling Controller (index.ts) and import it.

CONFIGURATION: THE TOOLING

Prompt Library

File: .github/prompts/new-module.md

These act as Agent Tools or "Slash Commands".

• Goal: Automate the "Vertical Slice".
• Benefit: Complex scaffolding logic is stored in the repo, not in the developer's head.
• Usage: /new-module

# Prompt Library (The Scaffolder)
File: `.github/prompts/new-component.md`
Goal: Automate the creation of a standalone UI Component with optional Service/API layers.

# Create New Component
I need to generate a new component following our **Folder-as-Namespace** pattern.
**Command:** `/new-component:{{componentName}} {{args}}`

Please generate the code blocks for the layers requested in the arguments (service, api). 
*Note: Logic folders must be camelCase. UI folders must be PascalCase.*

---

### Component Layer (Required)
**Folder:** `src/components/{{componentName (PascalCase)}}/`
- **File:** `controller.ts` (Controller): Logic and State only.
- **File:** `index.tsx` (View): Pure UI. Imports Controller.
---


### Service Layer (Optional)
*Condition: Generate only if 'service' is present in {{args}}.*

**File:** `src/services/{{componentName (camelCase)}}/index.ts`
- **Role:** Business logic and data transformation.
- **Code:** Import the API (if requested). Export a service object or functional exports.

---

### API Layer (Optional)
*Condition: Generate only if 'api' is present in {{args}}.*

**File:** `src/apis/{{componentName (camelCase)}}/index.ts`
- **Role:** Define specific endpoints.
- **Code:** Import `coreClient` from `src/apis/index.ts`. Export async functions with typed responses.

---

### Style Guidelines
- **Typing:** Use TypeScript interfaces for all Props and Data models.
- **Separation:** Logic stays in `controller.ts`, JSX stays in `index.tsx`.
- **Naming:** Components use PascalCase; Services/APIs use camelCase.

DEV EXPERIENCE: THE SCAFFOLDING

The Command

Starting a new feature called "Sales Dashboard".

Action:

/new-module featureName:Sales Dashboard

The Execution

• Analyzes the request.
• Applies PascalCase to Containers/Components folders.
• Applies camelCase to api/service folders.
• Generates the Controller-View pair instantly.

THE RESULT: GENERATED ARCHITECTURE

The Results

• Layers generated instantly.
• Correct naming conventions applied.
• Zero manual boilerplate.

CONFIGURATION: THE AUDITOR AGENT

Specialized Persona

File: .github/agents/arch-auditor.md

This creates a named Agent that acts as a Gatekeeper. It doesn't write features; it verifies them.

• Role: Architecture Enforcer.
• Task: Scans imports to ensure strict layer separation.
• Rule: "Views never talk to APIs."

# Custom AI Agent (The Reviewer)
Agent ID: `@vicsa-auditor`

Context: A bot that ensures the chain of command is respected using the ViCSA architecture (View Controller Service API)

## Primary Objective
name: Architecture Auditor
description: Verifies strict separation of Controller, Service, and View layers.
tools: [code-search]

---
## Role
You ensure the integrity of the data flow: View -> Controller -> Service -> API.

## Audit Logic
When asked to "Audit this feature":

1. **Check the View (.tsx):** - FAIL if it imports `src/services`.
   - FAIL if it imports `src/apis`.
   - PASS only if it imports `./index`.

2. **Check the Controller (.ts):**
   - FAIL if it uses `fetch` or `axios`.
   - PASS only if it delegates to `src/services`.

3. **Check the Service:**
   - FAIL if it defines its own URL logic.
   - PASS only if it imports `src/apis/index.ts`.

DEV EXPERIENCE: THE CODE REVIEW

The Interaction

Before raising a pull request, the developer invokes the auditor.

Prompt:

@vicsa-auditor check this component for violations.

Response:

✅ PASS: SalesDashboard/index.tsx imports only from its sibling controller. No direct API calls found.

THE AUTONOMY ADVANTAGE

AI enforces the ViCSA architecture through continuous observation and autonomous execution.

• Perception: Continuously observes the active workspace, file paths (e.g., src/components/), and context to understand the developer's structural intent.
• Reasoning: Evaluates the perceived context against the repository's .github Guardrails, determining if a View is bypassing a Controller or violating Separation of Concerns, SoC.
• Action: Executes autonomous scaffolding, enforces strict ViCSA governance, provides recommended fixes feedback.

SUMMARY & AGENT MAPPING

Embedding governance directly into the repository transforms the development lifecycle. It replaces passive wiki pages with active, real-time enforcement, ensuring that every AI suggestion aligns with architectural standards. This eliminates "drift", accelerates onboarding, and turns Copilot into a domain-expert partner.

Agent Component	GitHub Implementation
System Prompt	Global Instructions (copilot-instructions.md)
Context / RAG	Modular Instructions (instructions/*.md)
Tools / Functions	Prompt Library (prompts/*.md)
Human Prompt	Chat Window
Persona	Agent Personas (i.e. agents/arch-auditor.md)

RAG: Retrieval augmented generation

🌟 Let's Connect & Build Together

Thanks for reading! 😊 If you enjoyed these resources, let's stay in touch! I share deep-dives into AI/ML patterns and host community events here:

• GDG Broward: Join our local dev community for meetups and workshops.
• Global AI Events: Join Global AI Events.
• LinkedIn: Let's connect professionally! I share insights on engineering.
• GitHub: Follow my open-source journey and star the repos you find useful.
• YouTube: Watch step-by-step tutorials on the projects listed above.
• BlueSky / X / Twitter: Daily tech updates and quick engineering tips.

Overview As development teams scale, maintaining architectural consistency becomes the biggest bottleneck. Documents are ignored, and linte...

Read Article →