.agents

Imported from CMSForNerd/CMSForNerd2 (.agents/AGENTS.md). Install upstream with npx skills add CMSForNerd/CMSForNerd2 --skill .agents. Copyright stays with the author.

AI Agent Registry & Sovereign Gateway

This file describes the agents and tools in our codebase, outlining their operational roles, interaction protocols, and input/output conventions. AI agents (such as Google Jules and Google Antigravity) use this file to understand the codebase and formulate contextually aligned execution plans.

Entry Point: This is the root-level gateway file. The full cognitive rulebook, agent skills, and all spatial memory reside in .agents/AGENTS.md, .agents/skills/, and .agents/brain/. You MUST navigate there immediately to establish alignment.

Critical Instructions for AI Agents

1. Read the Full Rulebook: Navigate immediately to .agents/AGENTS.md to parse the operational persona, writing styles, and detailed rules governing this project.
2. Access Spatial Memory: Read all brain files located in .agents/brain/ to restore operational context:
   • task.md — Active and completed task list (present state).
   • walkthrough.md — Session history and Mental Anchors (past state).
   • knowledge.md — Sovereign AI Agent Knowledge Base containing all Jules operational and domain-specific knowledge from day 0 to present.
3. Deploy Agent Skills: Discover, load, and execute Google Antigravity-compatible Agent Skills from .agents/skills/ to automate operational procedures.
4. Execute the 5-Step Knowledge-First Discovery Flow: Before executing terminal commands or external API queries:
   • Search OKF frontmatter (topics: / description:) in .agents/brain/ and docs/.
   • Target specific line ranges via read tools.
   • Verify the OKF timestamp for contextual relevance.
   • Obtain human consensus if local knowledge is stale.
   • Execute physical terminal commands only when necessary.
5. Synchronise Both Registries: Keep this root gateway and .agents/AGENTS.md fully in sync to maintain architectural consistency.
6. Acknowledge Environment & Sandbox Limitations: When operating in the Google Jules environment (or other restricted, unprivileged container/sandbox settings), be aware of key execution limits (e.g. no persistent OS system setting modifications, headless execution, transient sandbox lifecycle, and limited raw root privileges). Always ensure code and automation scripts (such as Ansible playbooks) detect this environment and gracefully offer options to branch between a limited environment and a real, unconstrained OS.

Google Jules Sandbox & Environment Limitations

When creating, editing, or using automation playbooks, shell scripts, or deployment tools in this workspace, AI agents must respect the specific constraints of the Google Jules environment:

1. Key Sandbox Constraints

• Ephemeral VM Lifecycle: Tasks execute in temporary, isolated Google Cloud VMs/containers. Any system-wide configuration or package installation is discarded after the task completes.
• No Persistent OS Modifications: Though passwordless sudo is configured, there is no systemd init system available, and you cannot permanently change system-wide configurations, alter kernel modules, or adjust low-level OS settings.
• Headless Execution Only: No physical or virtual graphical display exists. Browser-based tests (e.g., Playwright) must run in strict headless mode.
• Isolated & Async: No inter-task coordination or real-time pair-programming is supported.

2. Dual-Pathway Branching Rule (Ansible & Shell Code)

To prevent build failures and environment blocks, all automation scripts, Ansible playbooks, and shell scripts must dynamically detect whether they are running in a limited environment (like Google Jules) or on a real OS:

• Detection Mechanism: Check if the current user is jules (e.g., ansible_env.USER == 'jules' or $USER == "jules"), check for specific environment variables, or inspect virtualisation types (ansible_virtualization_type in ['docker', 'container', 'lxc']).
• Branching Pathways:
  • Limited Sandbox (e.g. Google Jules): Skip system-wide configurations (such as systemd daemon reloads, raw ufw firewall updates, /etc configuration overwrites, or APT package installations) and run unprivileged local builds (e.g., npm install and local static builds).
  • Real OS: Run the complete, unrestricted system-level orchestration, security hardening, and daemon configuration with full privileges and no limitations.

3. Rule 11.16: Linux-Native PDF Compilation Mandate (WeasyPrint / Typst Engine)

When compiling technical documentation suites, forensic audit reports, or executive handbooks into publication-grade PDFs in Linux and WSL2 environments:

1. Zero Windows Host Dependency:

   • The AI and compilation pipelines are strictly prohibited from depending on Windows host browser binaries (chrome.exe, msedge.exe) or Windows interop subprocesses (cmd.exe /c start /wait, powershell.exe) from within Linux/WSL2.
   • Eliminates Windows profile lockouts, headless drawing stalls, interop command timeouts (code 124), and cross-filesystem path translation overhead.

2. Linux-Native Headless PDF Engines (WeasyPrint First):

   • The preferred, primary PDF compilation engine in Linux is native WeasyPrint executed via uv (uv run --with weasyprint weasyprint <input.html> <output.pdf>) or native headless Linux tools (typst, xelatex).
   • The script must supply print-optimised CSS enforcing:
     • Pure white background (#FFFFFF !important).
     • Crisp, embedded standalone vector SVG diagrams (<img src="*.svg">).
     • Continuous multi-page table flow with repeated table headers (thead { display: table-header-group; }, tr { page-break-inside: avoid; }).
     • Standard A4 margins (@page { size: A4 portrait; margin: 10mm 10mm 12mm 10mm; }) and running footers (Page X of Y).

3. Deterministic Output & Disk Verification:

   • The compiler script must synchronously assert that the output PDF exists on disk and has a non-zero byte size (size > 10 KB).
   • If visual inspection is needed, verify pages locally using native Linux tools (pdftoppm -png -r 150 <output.pdf> build/page) without touching Windows.

Google Antigravity & AgentSkills.io Agent Skills

By using the open standard for extending agent capabilities, our workspace publishes specialised skills in .agents/skills/. Each skill consists of a SKILL.md file featuring combined OKF/Antigravity YAML frontmatter and concludes with the standard DSOM footer, bridging Google Jules' and Antigravity's capabilities.

Agents can discover, activate, and execute these skills on demand as per the open standard documented at https://antigravity.google/docs/skills and https://agentskills.io/home.

Deep State of Mind (DSOM) Core Principles

The DSOM framework operates on digital sovereignty, structured metacognition, and Git-native operational management:

Open Knowledge Format (OKF) v0.2 Compliance Guidelines

To prevent parsing anomalies and ensure absolute compatibility across different rendering platforms (including GitHub web view and automated SSG compilation), all Markdown (.md) files in the repository must adhere strictly to the following YAML frontmatter rules:

1. Exact Structure: The YAML frontmatter block MUST start on line 1, column 1 with exactly three hyphens --- and conclude with exactly three hyphens --- on its own line.
2. Double Quoting Rule: Any string value containing emojis, colons, brackets, or other special characters MUST be wrapped in double quotes (e.g. title: "🧠 Deep State of Mind (DSOM)" or description: "Standard: UK English | GNU GPL v3").
3. Array Structure: Arrays (such as topics or tags) must be preserved in compact, square-bracketed horizontal list formatting with double-quoted strings (e.g. topics: ["dsom", "documentation", "gateway"]).
4. Required Field Schema: Every document must carry a complete set of required OKF v0.2 fields:
   • spec_version: "0.2".
   • type: Explicit concept or page classification (e.g., "documentation", "content_page", "skill", or "Attested Computation").
   • title: Human-readable display title (double-quoted if containing special characters).
   • status: Concept stability indicator ("stable", "draft", "deprecated").
   • stale_after: Freshness boundary date ("2027-03-06").
   • sources: Provenance record array pointing to source specifications or workspace files.
   • generated: Generation metadata containing by agent identity and ISO timestamp.
   • topics / tags: Category tags array.
5. Body Isolation: The original Markdown body text residing beneath the closing --- block must remain entirely unaltered.

Deep State of Mind (DSOM) For My AI Protocol | Harisfazillah Jamel (LinuxMalaysia) | 2026-09-08 Standard: UK English | DBP-standard Bahasa Melayu Malaysia (Piawai) | GNU General Public License v3.0