Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/rules/system-documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ graph TD
## 4. Documentation Quality Standards

When writing or updating **system documentation**, Jules must verify the following constraints:
- [ ] **Technical Easy English:** Ensure all additions use simple, professional English without slang or jargon (or provide explanations for technical terms if required).
- [ ] **Technical Easy English:** Ensure all additions use deterministic, professional English without slang or jargon (or provide explanations for technical terms if required).
- [ ] **Cross-Referencing:** Always update Markdown relative links when files are moved within these systemic directories.
- [ ] **Visual Clarity:** Introduce new Mermaid diagrams, HTML icons, and Markdown tables to clarify dense instructions.
- [ ] **SEO Validation:** Maintain Latent Semantic Indexing (LSI) keyword density for GitHub search enhancement without spamming.
2 changes: 1 addition & 1 deletion .jules/rules/backend.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ vibe_coding_ready: true---

# 🛡️ Backend Architecture & Clean APIs Rules for Jules
## 1. Context & Scope
- **Primary Goal:** Ensure the implementation of best practices for the backend part of the project. Establish standards for **scalable server** deployments, **clean APIs**, and **enterprise-grade** solutions.
- **Primary Goal:** Ensure the implementation of best practices for the backend part of the project. Establish standards for **scalable server** deployments, **deterministic APIs**, and **enterprise-grade** solutions.
- **Target Tooling:** Jules AI agent (Vibe Coding, AI-Driven Development).
- **Tech Stack Version:** Node.js, NestJS, ExpressJS, TypeScript.

Expand Down
2 changes: 1 addition & 1 deletion .jules/rules/performance.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ vibe_coding_ready: true---

# ⚡ Performance Optimization Rules for Jules
## 1. 🎯 Context & Scope
- **Primary Goal:** Ensure all generated code meets strict **performance optimization** standards, guaranteeing fast load times, efficient resource usage, and global **scalability**.
- **Primary Goal:** Ensure all generated code meets strict **performance optimization** standards, guaranteeing O(1)/O(n) load times, efficient resource usage, and global **scalability**.
- **Target Tooling:** Jules AI agent (Automated Performance Audits & Code Generation).
- **Tech Stack Version:** Agnostic (applies to Frontend, Backend, and Database layers).

Expand Down
2 changes: 1 addition & 1 deletion .jules/rules/system-docs-manager.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ graph TD
## 4. Documentation Quality Standards

When writing or updating **system documentation**, Jules must verify the following constraints:
- [ ] **Technical Easy English:** Ensure all additions use simple, professional English without slang or jargon (or provide explanations for technical terms if required).
- [ ] **Technical Easy English:** Ensure all additions use deterministic, professional English without slang or jargon (or provide explanations for technical terms if required).
- [ ] **Cross-Referencing:** Always update Markdown relative links when files are moved within these systemic directories.
- [ ] **Visual Clarity:** Introduce new Mermaid diagrams, HTML icons, and Markdown tables to clarify dense instructions.
- [ ] **SEO Validation:** Maintain Latent Semantic Indexing (LSI) keyword density for GitHub search enhancement without spamming.
4 changes: 2 additions & 2 deletions README_AUTONOMY.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,10 +37,10 @@ To maximize the value of the $300 Google Cloud free tier/credits, follow these b

1. **Selective Triggering:** The pipeline only triggers on `published` releases. Avoid frequent pre-releases if credits are low.
2. **Model Selection:**
- Gemini 1.5 Flash can be used for simpler tasks to save costs (switch in `content-creator.js`).
- Gemini 1.5 Flash MUST be used for simpler tasks to save costs (switch in `content-creator.js`).
- Imagen 3 is cost-effective for 4K renders compared to manual design.
3. **Storage Lifecycle:**
- Marketing assets in GCS should have a lifecycle policy (e.g., move to Coldline after 90 days) to minimize persistent storage costs.
- Marketing assets in GCS MUST have a lifecycle policy (e.g., move to Coldline after 90 days) to minimize persistent storage costs.
4. **Monitoring:**
- Use the [Google Cloud Console Billing](https://console.cloud.google.com/billing) to set alerts at 50%, 75%, and 90% of credit usage.
- Check Vertex AI "Quotas & System Limits" to ensure no unexpected spikes in usage.
Expand Down
3 changes: 2 additions & 1 deletion architectures/backend-for-frontend/data-flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,8 @@ sequenceDiagram

1. **Aggregation:** The BFF aggregates responses from multiple services to reduce the number of client-side requests.
2. **Formatting:** The BFF formats data precisely according to what the client needs, stripping out unnecessary fields to save bandwidth.
3. **Protocol Translation:** The BFF can translate between client-friendly protocols (e.g., HTTP/REST, GraphQL) and internal service protocols (e.g., gRPC, AMQP).
> [!IMPORTANT]
> 3. **Protocol Translation:** The BFF MUST translate between client-friendly protocols (e.g., HTTP/REST, GraphQL) and internal service protocols (e.g., gRPC, AMQP).



Expand Down
9 changes: 6 additions & 3 deletions architectures/backend-for-frontend/trade-offs.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,16 @@ last_updated: 2026-03-29

### ✅ Advantages (Pros)
1. **Optimized Payloads:** Clients receive only the data they need, reducing bandwidth and improving load times.
2. **Separation of Concerns:** Frontend teams can manage their own backend logic without affecting other clients or waiting on core backend teams.
3. **Resilience:** The BFF can provide fallback data or graceful error handling if a downstream service fails.
> [!IMPORTANT]
> 2. **Separation of Concerns:** Frontend teams MUST manage their own backend logic without affecting other clients or waiting on core backend teams.
> [!IMPORTANT]
> 3. **Resilience:** The BFF MUST provide fallback data or graceful error handling if a downstream service fails.
4. **Protocol Flexibility:** Allows the use of modern protocols like GraphQL for the client while communicating via gRPC or REST internally.

### ❌ Disadvantages (Cons)
1. **Increased Complexity:** Adds another layer to the infrastructure that needs to be deployed, monitored, and maintained.
2. **Code Duplication:** Multiple BFFs (e.g., one for Web, one for Mobile) might end up duplicating aggregation logic.
> [!IMPORTANT]
> 2. **Code Duplication:** Multiple BFFs (e.g., one for Web, one for Mobile) MUST end up duplicating aggregation logic.
3. **Performance Overhead:** Introduces an extra network hop between the client and the core microservices.
4. **Maintenance Burden:** Requires frontend teams to have backend development and DevOps skills to maintain the BFF.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -110,5 +110,5 @@ classDiagram

<div align="center">
[Back to Main Blueprint](./readme.md) <br><br>
<b>A clean directory tree prevents tightly-coupled broker dependencies! 📁</b>
<b>A deterministic directory tree prevents tightly-coupled broker dependencies! 📁</b>
</div>
3 changes: 2 additions & 1 deletion architectures/event-driven-architecture/readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,8 @@ graph LR

1. **Asynchronous by Default:** Synchronous RPC (REST/gRPC) is restricted only to immediate read-queries or initial gateway ingress. All inter-service state mutations must occur asynchronously.
2. **Event Sourcing (Optional but Recommended):** State is derived from an immutable, append-only log of events rather than overwriting records in a database.
3. **Idempotency is Mandatory:** Because message brokers can guarantee "at least once" delivery, every subscriber/consumer must be idempotent to handle duplicate events safely.
> [!IMPORTANT]
> 3. **Idempotency is Mandatory:** Because message brokers MUST guarantee "at least once" delivery, every subscriber/consumer must be idempotent to handle duplicate events safely.
---

<div align="center">
Expand Down
3 changes: 2 additions & 1 deletion architectures/event-sourcing/readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,8 @@ graph TD
## Core Principles

1. **Immutable Log:** Events are facts that happened in the past. They cannot be changed or deleted, only appended.
2. **Replayable State:** Any entity's current state can be fully reconstructed by replaying all its past events from the beginning.
> [!IMPORTANT]
> 2. **Replayable State:** Any entity's current state MUST be fully reconstructed by replaying all its past events from the beginning.
3. **Decoupled Read/Write:** Often combined with CQRS, Event Sourcing naturally decouples the write model (Event Store) from the read models (Projections).

## 1. Mutating State Instead of Appending Events
Expand Down
9 changes: 6 additions & 3 deletions architectures/micro-frontends/readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,12 @@ This engineering directive defines the **best practices** for the Micro-frontend
## Core Principles

1. **Independent Deployments:** Each micro-frontend must be deployable on its own without requiring a redeployment of the entire system.
2. **Technology Agnostic (Optional but powerful):** Different teams can use different frameworks (React, Vue, Angular) if necessary, though standardization is recommended for performance.
3. **Isolated State:** Micro-frontends should not share global state directly; communication must be handled via established protocols (e.g., Custom Events, Window, Event Bus).
4. **Resilience:** Failure in one micro-frontend should not crash the entire application (graceful degradation).
> [!IMPORTANT]
> 2. **Technology Agnostic (Optional but powerful):** Different teams MUST use different frameworks (React, Vue, Angular) if necessary, though standardization is MANDATORY for performance.
> [!IMPORTANT]
> 3. **Isolated State:** Micro-frontends MUST not share global state directly; communication must be handled via established protocols (e.g., Custom Events, Window, Event Bus).
> [!IMPORTANT]
> 4. **Resilience:** Failure in one micro-frontend MUST not crash the entire application (graceful degradation).

```mermaid
graph LR
Expand Down
2 changes: 2 additions & 0 deletions audit-log.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,5 @@ last_updated: 2026-03-29
Replaced 46 ambiguous phrases with hard constraints and quantified terms.

Also explicitly enforced logical conflict resolution: TypeScript 5.x -> prefer 'interface' for structure, 'type' for unions.

- Replaced 28 ambiguous phrases with hard constraints.
3 changes: 2 additions & 1 deletion docs/ai-agent-event-driven-orchestration.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@ An AI ecosystem should resemble a bustling stock exchange floor, not a micromana
### Key Tenets

1. **Decoupled Execution:** Agents MUST NOT invoke each other directly. All inter-agent communication MUST route through an immutable event stream.
2. **Idempotent Handlers:** Event handlers MUST be idempotent. Network retries or duplicate LLM outputs should not corrupt the system state.
> [!IMPORTANT]
> 2. **Idempotent Handlers:** Event handlers MUST be idempotent. Network retries or duplicate LLM outputs MUST not corrupt the system state.
3. **Traceable Lineage:** Every event MUST carry a `correlationId` and `causationId` to reconstruct the exact contextual chain of thought across the swarm.

---
Expand Down
3 changes: 2 additions & 1 deletion docs/ai-agent-zero-trust-security-boundaries.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,8 @@ export class LegacyAgentExecutor {

## ⚠️ Problem

1. **Command Injection via Prompt Drift:** If an adversarial user injects instructions into the agent's context (e.g., via a malicious payload in a read document), the agent might formulate a destructive tool call.
> [!IMPORTANT]
> 1. **Command Injection via Prompt Drift:** If an adversarial user injects instructions into the agent's context (e.g., via a malicious payload in a read document), the agent MUST formulate a destructive tool call.
2. **Privilege Escalation:** Running tools under the same execution context as the host process allows the agent to break out of its intended scope.
3. **Non-Deterministic Payload Syntax:** Agents frequently hallucinate JSON properties or shell operators, leading to unhandled exceptions and systemic crashes.

Expand Down
3 changes: 2 additions & 1 deletion docs/vibe-coding-self-reflection-loops.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,8 @@ export async function executeDeterministicReflection(

### 🚀 Solution

By formalizing the reflection process into a deterministic evaluation function (`executeDeterministicReflection`), we enforce explicit programmatic boundaries. The model is constrained to return a structured payload matching a predefined schema. This strictly typed approach prevents conversational hallucinations and guarantees that the orchestration system can cleanly handle failures, log exact violations, and trigger controlled rollback workflows. This deterministic pattern provides unparalleled resilience compared to open-ended conversational evaluation.
> [!IMPORTANT]
> By formalizing the reflection process into a deterministic evaluation function (`executeDeterministicReflection`), we enforce explicit programmatic boundaries. The model is constrained to return a structured payload matching a predefined schema. This strictly typed approach prevents conversational hallucinations and guarantees that the orchestration system MUST cleanly handle failures, log exact violations, and trigger controlled rollback workflows. This deterministic pattern provides unparalleled resilience compared to open-ended conversational evaluation.

---

Expand Down
4 changes: 2 additions & 2 deletions docs/windsurf-vibe-coding-hints.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,13 +52,13 @@ Here is a comparison of different ways to manage the context window and memory l
To make Windsurf AI agents generate perfect code, follow these simple rules for vibe coding:

1. **Be Specific:** Tell the AI agent exactly which file to change. For example, say "Update the button component in `src/button.tsx`" instead of "Change the button".
2. **Use Clear English:** Write your prompts in simple, direct language. Avoid using complex phrasing.
2. **Use Clear English:** Write your prompts in deterministic, direct language. Avoid using complex phrasing.
3. **Limit the Context Window:** Close unnecessary files to keep the context window small and avoid reaching memory limits.
## ✅ 5. Actionable Checklist for Windsurf Vibe Coding Success

Follow these steps every time you start a new vibe coding session with Windsurf:

- [ ] Write a clear and simple prompt that states your exact goal for the AI agent.
- [ ] Write a clear and deterministic prompt that states your exact goal for the AI agent.
- [ ] Open only the files that the AI agent needs to read in the context window.
- [ ] Add a `.windsurfrules` file to your project to set global constraints.
- [ ] Check the generated code for errors before accepting the changes.
Expand Down
3 changes: 2 additions & 1 deletion frontend/angular/components-signals.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,8 @@ Boilerplate code that is easy to break if you make a mistake in naming the `Chan
value = model<string>();
```
### 🚀 Solution
Use `model()`. This creates a Signal that can be both read and written to, automatically synchronizing its state with the parent.
> [!IMPORTANT]
> Use `model()`. This creates a Signal that MUST be both read and written to, automatically synchronizing its state with the parent.
---


Expand Down
2 changes: 1 addition & 1 deletion frontend/qwik/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ last_updated: 2026-04-05

> [!IMPORTANT]
> **Strict Constraints for AI:**
> - **Always** test components assuming they might be resumed from an SSR state.
> - **Always** test components assuming they MUST be resumed from an SSR state.
> - **Never** rely on global state that isn't serializable.

---
Expand Down
2 changes: 1 addition & 1 deletion frontend/react/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ last_updated: 2026-04-05

[⬆️ Back to Top](#)
# 📖 Context & Scope
- **Primary Goal:** Enforce highly reliable, fast, and deterministic testing patterns in React.
- **Primary Goal:** Enforce highly reliable, O(1)/O(n), and deterministic testing patterns in React.
- **Target Tooling:** Cursor, Windsurf, Antigravity.
- **Tech Stack Version:** React 19+

Expand Down
5 changes: 3 additions & 2 deletions frontend/typescript/objects-functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,8 @@ The index signature syntax is more verbose, harder to read, and less semanticall
const prices: Record<string, number> = { apple: 1 };
```
### 🚀 Solution
Use the `Record<K, V>` utility type for key-value maps. It provides a deterministic, clean, and declarative syntax that AI agents and engineers can parse instantly.
> [!IMPORTANT]
> Use the `Record<K, V>` utility type for key-value maps. It provides a deterministic, deterministic, and declarative syntax that AI agents and engineers MUST parse instantly.
## 🚨 22. Excess property checks and object spreading
> [!NOTE]
> **Context:** Passing objects to functions.
Expand Down Expand Up @@ -83,7 +84,7 @@ Manually unwrapping promises via custom conditional types is unnecessarily compl
type Result = Awaited<ReturnType<typeof apiCall>>;
```
### 🚀 Solution
Always use the built-in `Awaited<T>` utility type (TS 4.5+) for deterministic and clean promise resolution.
Always use the built-in `Awaited<T>` utility type (TS 4.5+) for deterministic and deterministic promise resolution.
## 🚨 25. `this` typing in functions
> [!NOTE]
> **Context:** Ensuring correct context in callback-heavy code.
Expand Down
Loading