🚀Home

README.md

🧠 Deep State of Mind (DSOM) For My AI Protocol

Bridging the gap between Human Architectural Intent and AI Execution for Open Source Sovereignty.

🛠️ Framework Overview

The Deep State of Mind (DSOM) For My AI Protocol ensures architectural sovereignty through:

1. Contextual Persistence: Using .agent/brain/ artifacts.

2. Multi-AI Alignment: Synchronising Gemini, Claude, and Copilot.

3. Linguistic Standards: UK English and DBP-standard Malay.

4. ITIL 4 Alignment: Operating as a "Service Relationship" for Value Co-creation.

🏛️ The Sovereign Framework (5W1H)

The Deep State of Mind (DSOM) is a metacognitive governance framework designed to prevent "Context Decay" in AI-assisted development. It transforms a standard LLM into a Cognitive Digital Twin of the Lead Architect.

• Who: Managed by the Lead Architect (Harisfazillah Jamel) and the AI Partner.

• What: Integrates Clean Architecture with the CRISP Operational Strategy.

• When: Executed daily via SOD/EOD Rituals and weekly via the Sunday Audit.

• Where: Hosted in the sovereign .agent/brain/ artifacts.

• Why: To ensure Sovereign Portability and eliminate vendor lock-in.

• How: Enforced through Atomic Git Hygiene and mandatory Handshake protocols.

🏛️ Section 1.1: The CRISP² Methodological Hierarchy

To maintain Sovereign Integrity, the DSOM protocol is structured using a four-level hierarchical process model. This ensures that every action taken by the Cognitive Digital Twin is mapped to a specific level of abstraction.

Level	CRISP-DM Category	DSOM Implementation	SSoT Artifact
L1	Phases	Rituals: Start-of-Day (SOD), Active Flow, and End-of-Day (EOD).	RITUAL-OF-TRANSITION.md
L2	Generic Tasks	Mandates: The CRISP Pillars (Context, Review, Iteration, Single-purpose, Partnership).	AI-MASTER-PROTOCOL.md
L3	Specialised Tasks	Architectural Layers: Implementation of Entities, Use Cases, and Drivers.	OPERATIONAL-GUIDE.md
L4	Process Instances	History: The concrete record of logic breakthroughs and mental anchors.	.agent/brain/walkthrough.md

🏥 Section 1.2: ITIL 4 Service Alignment

We adhere to the ITIL 4 Service Value System (SVS) to ensure that the code we generate provides actual measurable value, not just "output."

• Service Provider: The AI Agent (Providing Intelligence).

• Service Consumer: The Lead Architect (Defining Requirements).

• Value Co-creation: The "Handshake" is the negotiation of value.

• Service Knowledge Management System (SKMS): The .agent/brain/ directory acts as the SSoT for all service knowledge.

🧠 The Logic of the Hierarchy (The 'Why')

• Stability (L1-L2): The Phases and Mandates are Stable. They do not change regardless of whether the project is in Python, PHP, or Bash.

• Flexibility (L3): The Specialised Tasks adapt to the Clean Architecture requirements of the specific project.

• Auditability (L4): The Process Instances provide the Audit Trail required for the Sunday Human Refresh, ensuring the Architect's mental map is always in sync with the repository state.

---

📝 Description

Deep State of Mind (DSOM) is a metacognitive framework designed to prevent "Context Decay" in AI-assisted software development. While standard AI interactions are transactional, DSOM creates a persistent and structural bridge between the developer's expertise and the AI's generation capabilities.

The Deep State of Mind (DSOM) protocol is designed to ensure the synchronisation of architectural intent across diverse AI agents. It prioritises the authorisation of local 'Brain' artifacts as the single source of truth, preventing vendor lock-in and ensuring sovereign portability.

This project provides the tools and directory structures necessary to transform a standard AI (like Google Gemini, Claude, Copilot or ChatGPT) into a Cognitive Digital Twin of the Lead Architect. It enforces high-availability standards, strict architectural laws, and pedagogical integrity across long-term open-source projects.

It was forged in the CMSForNerd v3.5 Laboratory to ensure that AI agents (Gemini, Copilot, Cursor) operate not just as coders, but as Cognitive Digital Twins of the Lead Architect. It enforces high-availability standards, strict architectural laws (Zero-Global, Pair-Logic), and pedagogical integrity across long-term open-source projects.

Features

• State Persistence: Uses .agent/brain/ artifacts to bridge sessions and maintain context across different AI chats.

• Intelligence Audit: A mandatory "Pre-Flight" script verifies the physical environment and Git state before any code is written.

• Root-Aware Automation: Tools are designed to function correctly from any subdirectory within a Git repository.

• Sovereignty Focused: Built specifically for Linux-agnostic, portable, and secure open-source development under the GPLv3 license.

---

🖼️ Visuals

The DSOM workflow ensures that the AI's "Mind" is always synced with the "Physical" state of the code.

[ Physical Git State ] <---> [ .agent/brain/ ] <---> [ AI Agent Intelligence ]
          ^                        |                          ^
          |________________________|__________________________|
                         (The DSOM Handshake)

---

⚙️ Installation

Requirements

• Operating System: Linux (Optimized for Enterprise distributions like Ubuntu, AlmaLinux, RHEL).

• Version Control: Git.

• Environment: Any programming language (The auditor auto-detects PHP, Node.js, Python, and Go).

Setup

1. Clone the Repository:

   git clone https://github.com/linuxmalaysia/deep-state-of-mind-for-my-ai.git
   cd deep-state-of-mind-for-my-ai

2. Initialize the Brain: Create the required context files (this will not overwrite existing files):

   bash tools/init-brain.sh

3. Set Permissions:

   chmod +x tools/*.sh
   chmod +x tools/*.sh

2.1 Adoption & Upgrade Scenarios

• Adopting into an existing project? See HOWTO: Adopt DSOM (Brownfield).

• Upgrading from v4? See HOWTO: Upgrade DSOM.

---

🚀 Usage

1. The Pre-Flight Audit

Before starting any development session, run the auditor to ensure your Git state and environment are ready:

./tools/audit-pre-flight.sh

2. Engaging the AI

Initialize your AI session by providing it with the contents of the .agent/brain/ folder. This gives the AI your "Deep State of Mind" regarding:

• task.md: What we are doing right now.

• walkthrough.md: What we did in the last session.

• implementation_plan.md: The long-term roadmap.

The implementation_plan.md must serve as the Long-Term Strategic Roadmap. Unlike task.md (which is for today) or walkthrough.md (which is for the past), this file defines the Vision and Phases of the DSOM project.

To engage DSOM, initialize your AI session with the Master Directive.

Example Prompt:

"Initialize DSOM Protocol. Reference docs/AI-MASTER-PROTOCOL.md and perform the Intelligence Audit. Synchronize with .agent/brain/walkthrough.md .agent/brain/task.md and .agent/brain/implementation_plan.md before proposing code."

Expected Output: The AI will acknowledge your architectural laws (e.g., "Zero-Global Pattern") and refuse to proceed until it has verified the current Git delta.

🚀 The Reanimation Engine (tools/reanimate.sh)

The reanimate.sh script is the primary mechanism for maintaining the Deep State of Mind (DSOM) across different AI sessions, providers (Gemini, Claude, GPT), or hardware changes. It automates the "Knowledge Injection" process required for a successful Start of Day (SOD).

🛠️ What it Does

1. Aggregates Brain Artifacts: Combines task.md, the full walkthrough.md, and implementation_plan.md.

2. Contextualizes Identity: Injects the README.md and AI-MASTER-PROTOCOL.md to establish the AI's role and the Lead Architect's authority.

3. Physical Sync: Appends the last 30 Git commits to ensure the AI understands the actual code changes made on disk.

4. Manual State Injection: Prompts the user for any uncommitted "Mental Flow" or Master Prompt overrides from previous sessions.

5. Enforces Handshake: Appends the mandatory Handshake command for the AI to summarize the last Mental Anchor.

📋 Usage (Start of Day Ritual)

1. Generate the Manifest:

   bash tools/reanimate.sh
   

2. Review & Secure: Run tools/privacy-guardian.sh to ensure no sensitive data is present in the generated sod_manifest_YYYY-MM-DD.txt.

3. Reanimate the AI: Upload the manifest file to your AI chat and provide the following prompt:

"Summarize the current Mental Anchor after you have read the file uploaded."

• Output: Both terminal screen and a timestamped file (sod_manifest_yyyy-mm-dd.txt).

🕯️ The Ritual of Transition (Persistence Logic)

To maintain the Deep State of Mind across different AI models (Gemini, Claude, or local LLMs) and different accounts, users must follow the Ritual of Transition.

This protocol ensures that:

1. The AI is reanimated with the correct architectural laws.

2. The "Mental Anchor" is preserved so work resumes exactly where it stopped.

3. The project remains Sovereign—independent of any specific AI provider's memory limits.

See docs/RITUAL-OF-TRANSITION.md for the full checklist.

---

We will break down these three core files using the Why, What, Who, When, and How framework. This ensures that any user (or AI agent) understands not just the content, but the strategic intent behind them.

1. .agent/brain/task.md

The "Cutting Edge" of Development

• WHY: To solve "Short-Term Memory Loss" in AI. Without this, an AI agent often forgets the specific sub-task it was working on if the chat session is interrupted or hits a token limit.

• WHAT: A granular, checklist-oriented file that tracks immediate objectives. It represents the "Present" state of the project.

• WHO: Managed by the AI Agent (under human supervision). The AI updates this file as it completes sub-tasks to provide a "handover" for the next session.

• WHEN: Updated continuously during a work session. Every time a feature is finished or a bug is squashed, this file is modified.

• HOW: * Use Markdown checkboxes (- [ ] for pending, - [x] for done).

• Keep tasks "Atomic"—no task should be so large that it takes more than one session to complete.

• Always verify against this file during the "Morning Ritual" handshake.

---

2. .agent/brain/implementation_plan.md

The Strategic Roadmap

• WHY: To ensure the project doesn't suffer from "Scope Creep." It anchors the AI to the long-term vision so it doesn't suggest refactors that contradict the final goal.

• WHAT: A high-level document divided into Phases (e.g., Phase 1: Infrastructure, Phase 2: Core Logic). It represents the "Future" state of the project.

• WHO: Authored by the Lead Architect (Harisfazillah Jamel). The AI refers to this as a "Non-Negotiable" map.

• WHEN: Created at the start of a project and updated only when there is a major shift in technical strategy or versioning (e.g., moving from v4.1 to v5.0).

• HOW:

• List major technical milestones (e.g., "Implement HA Clustering").

• Define the "Definition of Done" for each phase.

• The AI must trigger a Stop Condition if a user request deviates from this plan.

---

3. docs/AI-MASTER-PROTOCOL.md

The Sovereign Constitution

• WHY: To enforce "Architectural Sovereignty." It prevents the AI from acting like a generic chatbot and forces it to adopt the persona of a Senior Systems Architect who respects 35+ years of ICT standards.

• WHAT: The primary governance document containing the "Laws of the System" (Zero-Global Pattern, Sovereign Portability, Pedagogical Documentation).

• WHO: The Supreme Authority for all AI Agents. It is the first document "injected" into any new AI session.

• WHEN: Consulted every time a new chat session begins or when a model switch (e.g., Gemini to Claude) occurs.

• HOW:

• Contains the Handshake Protocol (The mandatory questions the AI must ask before coding).

• Defines the Execution Standards (VCS Hygiene, Language requirements like PHP 8.4+).

• Establishes the Identity of the AI as the "Cognitive Digital Twin" of the Lead Architect.

---

🕯️ The Rituals of Transition

🌅 1. Reanimation (Start-of-Day)

Before writing code, run the bootloader to inject the "Deep State" into the AI:

bash tools/reanimate.sh

Ask the AI: "Summarise the current Mental Anchor and verify layer compliance."

🛠️ 2. Active Flow (The Guardrails)

Maintain the Zero-Global Pattern and Sovereign Portability. Update the walkthrough.md after every successful logic breakthrough.

🌙 3. Hibernation (End-of-Session)

Secure the session state to prevent context loss:

1. Define the Mental Anchor (current logical stopping point).

2. Update task.md with tomorrow's SOD targets.

3. Perform a Sovereign Save (Atomic commit of brain artifacts).

4. Request a Metacognitive Briefing for the next agent.

📅 4. Sunday Audit (Human Refresh)

Every Sunday, the Lead Architect performs a Dry-Run Audit of all repository files to re-index the human mental map and ensure system-wide synchronisation.

---

📂 The Trinity of Persistence

Artifact	Temporal State	Primary Purpose	Authority
task.md	Present	Immediate focus & checklist.	AI-Driven
walkthrough.md	Past	Context, "Why", & Mental Anchors.	Hybrid
implementation_plan.md	Future	Strategic Roadmap & Phases.	Human-Driven
AI-MASTER-PROTOCOL.md	Eternal	Governance, Laws, & Identity.	Human-Driven

---

⚙️ Setup & Tools

1. Initialise: bash tools/init-brain.sh

2. Audit Environment: ./tools/audit-pre-flight.sh

3. Privacy Check: ./tools/privacy-guardian.sh (Run before sharing manifests).

---

🗺️ Roadmap

• v4.1: Initial release with Root-Aware scripts.

• Licensing: Full GPLv3 integration for open-source sovereignty.

• v4.5: Automated "Session Summary" generator for walkthrough.md.

• v5.0: Integration with local LLMs via Ollama for offline DSOM.

---

🤝 Contributing

We welcome contributions that improve the strictness and reliability of the protocol. Please read our CONTRIBUTING.md for details on our code of conduct, atomic commit standards, and the DSOM Trinity sync process.

• Requirements: All PRs must include a walkthrough.md logic update.

• Standard: Use Atomic Commits (one file per commit with descriptive messages).

• Documentation: New patterns must be documented in the Project Knowledge Graph.

I use Atomic Commits for this project. Please ensure each pull request or commit targets a single file or logic change with a descriptive message.

Example: The Final Atomic Commit

Now, let's practice the "one-by-one" method you requested to save this to your repo:

# 1. Add the README
git add README.md

# 2. Commit with detailed comment
git commit -m "docs: finalize README.md with detailed DSOM architecture, visual workflow descriptions, and tool usage"

# 3. Push to GitHub
git push

---

🚦 Your Day 1 Starting Point

When you sit down tomorrow, your first prompt to the AI will be:

"Initialize DSOM Protocol. Perform the Intelligence Audit. Then, use DSOM_TEMPLATE.md to initialize today's session log in .agent/brain/walkthrough.md based on the current task."

---

🏗️ Starting a New Project (The DSOM Template)

You can use this repository as a boilerplate for any new AI-assisted project.

📋 Cloning Workflow

1. Clone the DSOM framework:

   git clone [https://github.com/linuxmalaysia/deep-state-of-mind-for-my-ai.git](https://github.com/linuxmalaysia/deep-state-of-mind-for-my-ai.git) my-new-app
   cd my-new-app

2. **Run the Reset Tool:**
```bash
bash tools/template-reset.sh

This will delete the old .git history, initialize a fresh Git repo, and clear the brain files. 3. Initialize the AI: Generate your first manifest (bash tools/reanimate.sh) and use the Universal DSOM Reanimation Prompt to start your new Gemini/Claude session.

---

🧠 Personalization Ritual (Saved Info)

To establish a permanent Cognitive Digital Twin relationship, utilize Gemini's Saved Info feature. This ensures the AI persists your identity, architectural laws, and linguistic standards across all chat sessions.

Refer to docs/PERSONALIZATION.md for the configuration blocks.

---

🤖 AI Provider Support

• ♊ Google Gemini Setup

• 🎭 Anthropic Claude Setup

🛡️ GitHub Copilot Setup

Copilot is also synchronised to follow DSOM protocols using UK English and DBP-standard Malay.

• Automated Guardrails: Instructions are sourced from .github/copilot-instructions.md.

• Contextual References: See docs/COPILOT-SETUP.md for manual chat commands and file reference rituals.

---

🏛️ Technical Architecture

This project implements the Deep State of Mind (DSOM) For My AI Protocol layered with Clean Architecture principles:

• Sovereign Logic: Framework-independent core.

• Layered Security: Clear boundaries between business logic and drivers.

• AI-Navigable: Structured for high-precision context retrieval via CRISP strategy.

🛡️ The DOSM CRISP Operational Strategy

To prevent context decay and architectural drift, all interactions within this repository follow the DOSM CRISP strategy. This ensures the "Sovereign Core" remains untainted by AI hallucinations.

1. Context Awareness: Always initialise sessions by synchronising with the .agent/brain/ artifacts.

2. Review & Record: Every logic change must be documented in walkthrough.md and committed via Atomic Git Hygiene.

3. Iteration: Progress is achieved through incremental, atomic changes. We avoid monolithic refactors to maintain stability.

4. Single-purpose Prompts: Each interaction must focus on a specific sub-task (e.g., a single Use Case or Entity) to ensure high-precision output.

5. Partnership: The AI operates as a Senior Systems Architect (Cognitive Digital Twin), upholding the standards set by Harisfazillah Jamel.

---

CRISP-DM (Cross-Industry Standard Process for Data Mining) is the industry-standard methodology for managing data science and data mining projects. Developed in the late 1990s by a consortium including Daimler-Benz, NCR, and SPSS, it was designed to be non-proprietary, tool-neutral, and application-independent.

🏛️ The 4-Level Hierarchical Structure

One of the most powerful (and often overlooked) aspects of CRISP-DM is its hierarchical process model. It breaks down projects into four levels of abstraction:

1. Phases (L1): High-level stages of the data mining process (e.g., Business Understanding).

2. Generic Tasks (L2): Stable actions that apply to all projects (e.g., "Clean Data").

3. Specialised Tasks (L3): Specific actions tailored to a particular situation (e.g., "Clean missing categorical values in a SQL database").

4. Process Instances (L4): A concrete record of what actually happened in a specific project (e.g., the logs of a Python cleaning script run on Jan 12th).

🔄 The 6 Operational Phases

The life cycle of a CRISP-DM project is cyclical, meaning insights from later phases often trigger a return to earlier ones.

1. Business Understanding: Focuses on project objectives from a business perspective.

2. Data Understanding: Initial collection and familiarisation to identify quality issues or hidden insights.

3. Data Preparation: The "heavy lifting" phase where data is cleaned, transformed, and formatted for modelling.

4. Modelling: Selecting and applying various modelling techniques (e.g., machine learning algorithms).

5. Evaluation: Ensuring the model actually meets the business objectives set in Phase 1.

6. Deployment: Organising the results and integrating the model into a production environment.

🧠 Why This Matters for Our AI Protocol

In our DSOM framework, we use this same hierarchy to prevent "Context Decay." By mapping your AI interactions to these levels:

• L1-L2 (Rituals & Protocols): Stay stable and never change.

• L3 (Clean Architecture): Adapts to the specific code.

• L4 (Walkthrough Artifacts): Captures the "Mental Anchor" of our current work.

---

👤 Authors and Acknowledgment

• Lead Architect & Author: Harisfazillah Jamel – A veteran with 35+ years of ICT & Open Source Leadership.

• AI Thought Partner: Google Gemini - Assisted in refactoring scripts and optimizing documentation.

• Inspiration: The CMSForNerd v3.5 Laboratory community.

---

📄 License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

---

⚠️ Disclaimer & Usage Policy

🎯 Purpose of this Protocol

At Your Own Risk: This protocol is shared for educational purposes. The author is not liable for data loss or AI hallucinations. Users are responsible for validating the stability of their own "Digital Twins."

The Deep State of Mind (DSOM) For My AI Protocol was developed by Harisfazillah Jamel (LinuxMalaysia) to solve the challenge of Context Decay and Knowledge Divergence across multiple AI platforms (e.g., Google Gemini, Anthropic Claude, GitHub Copilot).

The goal is to maintain a "Sovereign Mental Anchor" that ensures different AI agents and chat sessions respond with the same pedagogical logic, linguistic standards, and technical precision, regardless of the platform used.

🛡️ Responsibility & Risk

• At Your Own Risk: The documentation, scripts, and configurations provided in this repository are shared for educational and "Proof of Concept" purposes. Use of these materials is strictly at your own risk.

• No Warranty: These tools are provided "as is" without warranty of any kind, express or implied. The author shall not be held liable for any data loss, infrastructure failure, or AI hallucinations resulting from the implementation of this protocol.

• Sovereign Implementation: Users are encouraged to adapt the ideas presented here to their own specific environments, but they remain responsible for validating the security and stability of their own "Cognitive Digital Twins."

---

By using this protocol, you acknowledge that you have read and understood these terms.

---

🚦 Project Status

ACTIVE. This framework is the primary governance model for LinuxMalaysia's AI-assisted development. ACTIVE. The DSOM protocol is actively used to govern the development of CMSForNerd and related high-availability infrastructure projects.

---

Current Status: ACTIVE | Last Human Audit: 2026-01-16

---

🆕 Recent Updates (2026-01-16)

The following modules have been integrated into the DSOM Protocol to support Scaling & Community:

🤖 Multi-Agent Protocols (docs/MULTI-AGENT-PROTOCOLS.md)

We have standardized the configuration for:

• Autonomous Workers: Devin, CrewAI, AutoGen.

• IDE Co-Pilots: Cursor, Windsurf, GitHub Copilot.

• Templates available in docs/agent-configs/.

📚 Documentation Infrastructure (tools-and-automation/)

• Metric: 100% Documentation Coverage for shell scripts.

• Platforms: Ready for GitBook, MkDocs, and mdBook.

• Universal Config: mkdocs.yml and book.toml included.

👥 Community Governance (.github/)

• Gates: Automated ISSUE_TEMPLATE and PULL_REQUEST_TEMPLATE.

• Scribe: Automated Session Logging via tools/generate-walkthrough.sh.

🛡️ Phase 5: Privacy Hardening (Level 5 Optimization)

• Fail-Closed: privacy-guardian now blocks Emails, AWS Keys, and Private Keys.

• Manifest Safety: Explicit data dump exclusions in .gitignore.

🏥 Phase 6: ITIL 4 Service Alignment

• Protocol: Injected "Law 11" (Service Management) into the Master Protocol.

• Governance: Defined the Service Value Chain in docs/ITIL-ALIGNMENT.md.