From 90c0db2822eb47be3a62599bd6edebbc8caa2cb9 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Thu, 4 Jun 2026 16:13:40 +0000 Subject: [PATCH] Add centralized ARCHITECTURE.md for core system design patterns MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ### Context & Rationale Currently, our documentation is heavily optimized for machine consumption (e.g., `SKILL.md`) and siloed within individual skill directories. This makes it challenging for new contributors to grasp the high-level system architecture, leading to increased onboarding time and potential architectural drift. The goal of this PR is to centralize our core principles—orchestration, safety, and file isolation—into a single, human-readable root document. By providing a "source of truth" for system behavior, we ensure that developers understand how parallel tasks are managed and how repository integrity is maintained before they begin writing code. ### Key Changes #### 1. Created `ARCHITECTURE.md` Established a root-level guide that focuses on high-level principles rather than specific business logic: * **Orchestration Workflow:** Documents the transition from the Planning agent to the Dispatch phase, clarifying how parallel sessions are managed. * **Safety Layers:** Synthesizes our multi-layered defense strategy, including preventative prompt-level "Critical Rules" and corrective validation phases during PR merging. * **Conflict Resolution (File Ownership Matrix):** Explains the logic used to pre-validate task boundaries, ensuring that parallel agents do not create merge conflicts by touching the same files. * **Bootstrapper Pattern:** Defines the recurring pattern for encapsulating logic and injecting capabilities into target environments. #### 2. Updated `README.md` * Added a dedicated **Architecture** section in the root README. * Provided a direct link to the new guide to improve discoverability for new developers and security reviewers. ### Key Design Decisions * **Human-Centric Design:** Unlike our automated documentation, this file uses conceptual descriptions and clear Markdown formatting (including a Table of Contents) specifically for developer orientation. * **Avoidance of Redundancy:** The guide is designed to link to existing technical resources where necessary, rather than duplicating low-level implementation details that are subject to frequent change. * **Static Maintenance:** We have opted for a manually maintained document at this stage to prioritize clarity and narrative flow over automated synchronization. ### Acceptance Criteria Met - [x] `ARCHITECTURE.md` exists in the root directory. - [x] Includes sections on orchestration, safety, and conflict resolution. - [x] Uses terminology consistent with the underlying codebase (e.g., "Dispatch phase," "Planning agent"). - [x] Document is easily navigable via standard Markdown viewers. --- ARCHITECTURE.md | 37 +++++++++++++++++++++++++++++++++++++ README.md | 4 ++++ 2 files changed, 41 insertions(+) create mode 100644 ARCHITECTURE.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..e1bf6af --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,37 @@ +# Centralized Architectural Guide + +## Table of Contents +1. [Overview](#overview) +2. [Task Orchestration and Parallel Session Management](#task-orchestration-and-parallel-session-management) +3. [File Ownership and Conflict Resolution](#file-ownership-and-conflict-resolution) +4. [Safety Layers](#safety-layers) +5. [The Bootstrapper Pattern](#the-bootstrapper-pattern) + +## Overview +This document provides a central, human-readable reference for the core system behaviors of the repository. It focuses on the global architecture, covering orchestration, safety, file isolation, and deployment patterns to accelerate developer onboarding and prevent architectural drift. Detailed, skill-specific logic can be found in the respective `SKILL.md` files within individual directories. + +## Task Orchestration and Parallel Session Management +The system relies on a multi-agent orchestration architecture to handle complex work streams efficiently. The primary workflow defines how the system transitions from initial planning to parallel execution: + +* **Planning Phase:** The **Planning agent** interprets the overarching goals and breaks them down into discrete, actionable tasks. It determines the necessary sequence and parallelism of these tasks. +* **Dispatch Phase:** During the **Dispatch phase**, the system assigns the planned tasks to specialized execution agents. This phase manages parallel session management, spinning up distinct sessions for agents to work concurrently. + +By segregating planning from execution, the system ensures that individual task agents remain focused on their specific objectives without losing sight of the broader architectural goals. + +## File Ownership and Conflict Resolution +To manage parallel tasks without creating merge conflicts, the architecture enforces a strict **File Ownership** principle. This guarantees isolation between parallel agents operating simultaneously. + +* **File Ownership Matrix:** Before any task enters the Dispatch phase, the system consults the **File Ownership Matrix**. This matrix maps specific files and directories to the agents assigned to modify them. +* **Pre-validation of Task Boundaries:** The system pre-validates task boundaries before execution begins. If the matrix detects that two parallel agents might attempt to modify the same file, the orchestration layer intercepts this and either serializes the tasks or reallocates boundaries. This proactive conflict resolution completely eliminates parallel file contention. + +## Safety Layers +To prevent AI agents from performing destructive actions, the system implements a multi-layered safety strategy. This strategy combines both preventative measures and corrective validation checks. + +* **Preventative Guardrails (Prompts):** At the earliest stage, agents are bound by **Critical Rules** embedded directly within their system prompts. These rules strictly define the acceptable actions and scopes for each agent, proactively limiting their capabilities to safe operations. +* **Corrective Guardrails (Validation):** Should an agent deviate from its intended behavior, corrective validation phases catch anomalies before they affect the main repository. This is primarily enforced through **sequential PR merging**. Rather than allowing agents to merge changes directly or simultaneously, each completed task generates a Pull Request that undergoes automated and/or manual validation phases. Only after successfully passing these checks is the code integrated, ensuring repository integrity. + +## The Bootstrapper Pattern +To maintain modularity and ease of deployment, the system employs a recurring **bootstrapper** pattern. This architectural pattern is used to install encapsulated logic into target environments. + +* **Encapsulation:** Instead of coupling the core orchestration engine with specific deployment scripts, individual skills and tools are packaged with their own bootstrapper mechanisms. +* **Installation:** When an agent requires a specific capability or needs to deploy logic to a target environment, it invokes the bootstrapper. The bootstrapper handles the environment setup, dependency injection, and initialization required to make the encapsulated logic fully operational in that specific context. This ensures consistent, reproducible environments across different agents and tasks. diff --git a/README.md b/README.md index 5e60be0..4561f31 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,10 @@ skills/[skill-name]/ └── README.md — User-facing documentation ``` +## Architecture + +If you are a new contributor or want to understand how the system manages parallel tasks, safety, and orchestration without creating merge conflicts, please read our [Centralized Architectural Guide](ARCHITECTURE.md). + ## Adding New Skills All new skills need to follow the file structure above to implement the Agent Skills open standard.