Add centralized ARCHITECTURE.md for core system design patterns#8
Draft
google-labs-jules[bot] wants to merge 1 commit into
Draft
Conversation
### 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.
digitalex
reviewed
Jun 4, 2026
| * **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 |
There was a problem hiding this comment.
We can remove this entire bootstrapper section [alex testing PR comments]
|
A comment for testing PR reactions |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.mdEstablished a root-level guide that focuses on high-level principles rather than specific business logic:
2. Updated
README.mdKey Design Decisions
Acceptance Criteria Met
ARCHITECTURE.mdexists in the root directory.