From 139ccc78538ee5542f80022afb2fd5d8f29b55e3 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 1 Sep 2026 07:46:02 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=8F=9B=EF=B8=8F=20Archie:=20Codify=20feat?= =?UTF-8?q?ure=20flags=20ADR=20and=20initialize=20repository=20Tech=20Rada?= =?UTF-8?q?r?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create ADR 0002 for Feature Flags Schema Validation & Decoupled Configuration. - Establish master ADR index in docs/adr/README.md. - Initialize Repository Tech Radar in docs/tech-radar.md covering 4 quadrants and 4 rings. - Record architectural journal entry in .Jules/archie.md. Co-authored-by: alehar9320 <5390430+alehar9320@users.noreply.github.com> --- .Jules/archie.md | 3 + .../0002-feature-flags-schema-validation.md | 33 ++++++++++ docs/adr/README.md | 10 +++ docs/tech-radar.md | 61 +++++++++++++++++++ 4 files changed, 107 insertions(+) create mode 100644 .Jules/archie.md create mode 100644 docs/adr/0002-feature-flags-schema-validation.md create mode 100644 docs/adr/README.md create mode 100644 docs/tech-radar.md diff --git a/.Jules/archie.md b/.Jules/archie.md new file mode 100644 index 00000000..192ebd51 --- /dev/null +++ b/.Jules/archie.md @@ -0,0 +1,3 @@ +2026-09-01 - Codify Feature Flags & Establish Tech Radar +Learning: Lack of explicit ADR master index and centralized Tech Radar allowed implicit patterns (like feature flag synchronization and prohibited CSS frameworks) to drift across multi-agent contributions. +Action: Enforce ADR 0002 for all feature flag modifications and maintain `docs/tech-radar.md` rings to guide autonomous agent decisions. diff --git a/docs/adr/0002-feature-flags-schema-validation.md b/docs/adr/0002-feature-flags-schema-validation.md new file mode 100644 index 00000000..2a0fafcf --- /dev/null +++ b/docs/adr/0002-feature-flags-schema-validation.md @@ -0,0 +1,33 @@ +# 0002. Feature Flags Schema Validation & Decoupled Configuration + +- **Status:** Accepted +- **Date:** 2026-09-01 +- **Deciders:** Autonomous Architect (Archie) / Repository Analysis + +## Context + +The repository contains multiple autonomous AI agents (such as Apex, Kinetic, Aurora, and Jules) shipping isolated micro-features and UI experiments. To isolate experimental features without modifying global routing, runtime layout logic, or incurring runtime build breaks, feature toggles are stored in `src/content/flags/config.json`. + +However, modifying or adding feature toggles in `config.json` without updating Content Collections validation schemas breaks content schema unit tests and type inference. + +## Decision + +All runtime feature flags must be declared centrally in `src/content/flags/config.json` and synchronized with the Zod schema in `src/content.config.ts`. + +Feature flags must follow standard boolean property defaults (e.g., `z.boolean().default(false)`). + +## Consequences & Tradeoffs + +- **Positive:** Ensures strict type safety, prevents runtime undefined flag access, and enables safe experimental isolation for all autonomous agents. +- **Negative / Risks:** Developers and AI agents must update two files (`config.json` and `src/content.config.ts`) when adding new flags. +- **Adoption Readiness:** Pattern is already fully operational in `src/content/flags/` and `src/content.config.ts`. + +## Directives for AI Agents + +- **Do:** + - Define new feature flags in `src/content/flags/config.json`. + - Synchronize any new feature flag with `src/content.config.ts` under the `flags` collection schema using `z.boolean().default(false)`. + - Use feature flags to isolate experimental routes, micro-interactions, or visual enhancements. +- **Don't:** + - Never add a flag to `config.json` without adding its Zod schema definition to `src/content.config.ts`. + - Never remove existing feature flags without checking component references across `src/`. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 00000000..9de635ab --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,10 @@ +# Architecture Decision Records (ADRs) + +Architecture Decision Records (ADRs) document key strategic and architectural decisions made for this repository. They describe the context, rationale, trade-offs, and enforceable Directives for AI Agents to prevent technical drift. + +## Index + +| ADR | Title | Status | Date | +| :--------------------------------------------------- | :-------------------------------------------------------- | :------- | :--------- | +| [0001](./0001-cloudflare-production-render-jules.md) | Cloudflare as production, Render as Jules test env | Accepted | 2026-08-24 | +| [0002](./0002-feature-flags-schema-validation.md) | Feature Flags Schema Validation & Decoupled Configuration | Accepted | 2026-09-01 | diff --git a/docs/tech-radar.md b/docs/tech-radar.md new file mode 100644 index 00000000..4daaf111 --- /dev/null +++ b/docs/tech-radar.md @@ -0,0 +1,61 @@ +# Repository Tech Radar + +## Quadrants + +### 1. Frameworks & Runtimes + +- **Adopt:** + - **Astro (v7.x):** Primary static site generator and SSG framework for all core pages. + - **TypeScript:** Strict type system for all application logic and utilities. + - **Cloudflare Workers (`@astrojs/cloudflare`):** Production rendering and edge serverless target. +- **Trial:** + - **Node Standalone Adapter (`@astrojs/node`):** Used exclusively for Jules test debugging environment on Render. +- **Assess:** + - **Wasm / Edge Module Extensions:** Evaluating potential client/edge compute extensions. +- **Hold:** + - **React / Vue / Svelte Component Frameworks:** Keep site lightweight using zero-framework Vanilla JS/CSS islands. + +### 2. Infrastructure & Cloud + +- **Adopt:** + - **Cloudflare Pages / Workers:** Production hosting environment (`wrangler.jsonc`). + - **Sentry (`@sentry/astro`, `@sentry/cloudflare`):** Error logging and application performance monitoring. +- **Trial:** + - **PostHog (`posthog-js`):** Web analytics and feature engagement tracking. +- **Assess:** + - **Cloudflare KV / Vectorize:** Autonomous AI assistant memory context storage. +- **Hold:** + - **Heavy Node Origin Hosting:** Production Node dynamic servers (migrated to Cloudflare edge). + +### 3. Tooling & AI Workflows + +- **Adopt:** + - **Vitest:** Unit testing framework for utility functions and content validation. + - **Prettier & ESLint:** Code formatting and static linting guardrails. + - **Jules & Autonomous Agent Fleet:** Multi-agent autonomous workflow operating under agent-specific directives. +- **Trial:** + - **Playwright:** End-to-end frontend visual verification. +- **Assess:** + - **MCP (Model Context Protocol):** Standardized tools and prompts interface for AI context extensions. +- **Hold:** + - **Manual Deployment Scripts:** Replaced by automated GitHub Actions CI/CD workflows. + +### 4. Patterns & Architecture + +- **Adopt:** + - **Feature Flags via Content Collections:** Decoupled JSON toggles validated via Zod schemas (`src/content.config.ts`). + - **Vanilla CSS Glassmorphic Styling:** Scoped CSS variables using 'Northern Lights' design language without external CSS frameworks. + - **Explicit Image Dimensions:** `width` and `height` declared on visual assets for zero Cumulative Layout Shift (CLS=0). +- **Trial:** + - **Pointer-Based Edge Stream Parsing:** High-performance buffer scanning in Cloudflare Worker SSE endpoints. +- **Assess:** + - **Canvas Lab Isolation (`src/pages/lab/`):** Dedicated route sandbox for interactive 3D/canvas visual features. +- **Hold:** + - **Tailwind CSS / CSS Utility Frameworks:** Prohibited to maintain pure CSS standard performance. + +## Rings + +- **Adopt:** High confidence, production-proven in this repo. Default choice for new work. +- **Trial:** High potential with low risk. Ready for isolated usage in minor features or scripts. +- **Assess:** Worth tracking and evaluating trade-offs; not yet recommended for active production code. +- **Hold:** Phasing out or proven problematic in our setup. Do not use for new work.