#7308 Fully Automated Workflows

Author: tobiu

.github/AI_QUICK_START.md

@@ -98,29 +98,35 @@ step showing how to install the Gemini CLI.
 npm i -g @google/generative-ai/cli
 ```
 
-## 5. The AI-Native Workflow in Action
+## 5. The AI-Native Workflow: A Partnership
 
-The goal of this system is not for you to manually run queries, but to empower an AI agent to do it for you. Here’s how
-the intended workflow looks:
+The goal of this system is to create a powerful partnership between you and the AI agent. To facilitate this, we use a dual-guide system:
+
+-   **`AGENTS.md`**: This is the rulebook for the **AI**. It contains the critical instructions, protocols, and constraints the agent must follow to be an effective contributor.
+-   **`WORKING_WITH_AGENTS.md`**: This is the playbook for **you**, the human developer. It provides essential strategies for guiding the agent, handling common issues, and maximizing its performance.
+
+Your first step before starting a session should be to familiarize yourself with the `WORKING_WITH_AGENTS.md` guide.
+
+### The Workflow in Action
+
+Here’s how the intended workflow looks:
 
 1.  **Start your AI Agent**: From the repo root, launch your AI agent of choice (e.g., Gemini CLI).
     ```bash
     gemini
     ```
-2.  **Give a High-Level Prompt**: Instead of feeding the AI context, you give it a goal and instruct it to use the tools
-    available in the repository.
+2.  **Give the Initial Handshake**: This is the most critical step. Your first prompt **must** direct the agent to its instructions.
+    > **Your Prompt:** "follow the instructions inside @AGENTS.md"
 
+3.  **Give a High-Level Prompt**: Once the agent has completed its initialization, you can give it a goal.
     > **Your Prompt:** "Explain the Neo.mjs two-tier reactivity model and provide a simple code example."
 
-3.  **The AI Takes Over**: An AI agent following the `AGENTS.md` protocol will then:
+4.  **The AI Takes Over**: An agent following the `AGENTS.md` protocol will then:
     *   **Formulate a query**: It will determine that "reactivity" is the key concept.
-    *   **Execute the tool**: It will run `npm run ai:query -- -q "reactivity" -t guide` and
-        `npm run ai:query -- -q "reactivity" -t src` on its own.
-    *   **Synthesize the answer**: After getting the paths to the most relevant guides and source files, it will read
-        them and use that fresh, accurate context to generate a comprehensive explanation and code example.
+    *   **Execute the tool**: It will run `npm run ai:query -- -q "reactivity" -t guide` on its own.
+    *   **Synthesize the answer**: After getting the paths to the most relevant guides and source files, it will read them and use that fresh, accurate context to generate a comprehensive explanation.
 
-This is the crucial difference: you are delegating the *research* task to the AI, making it a true partner that can
-autonomously navigate and understand your codebase.
+This is the crucial difference: you are delegating the *research* task to the AI, making it a true partner that can autonomously navigate and understand your codebase.
 
 ## 6. Common Troubleshooting
 

.github/ISSUE/epic-hacktoberfest-2025.md

@@ -31,9 +31,9 @@ Let AI do the heavy lifting while you learn. The one-time setup takes about 15 m
 - **Knowledge Base:** Building and querying the knowledge base uses the `text-embedding-004` model, which is free for up to **60 queries per minute**.
 - **AI Agent:** For interactive development, if you use the Gemini CLI, it uses the `gemini-pro` model, which provides up to **3 million tokens per day for free**.
 
-**1. Follow the [AI Knowledge Base Quick Start Guide](./AI_QUICK_START.md)**
-
-This will walk you through building the local knowledge base that the AI uses to understand the project.
+**1. Read the Guides:**
+   - **[Working with AI Agents](https://github.com/neomjs/neo/blob/dev/.github/WORKING_WITH_AGENTS.md):** First, read this playbook for you, the human developer. It provides essential strategies for guiding the agent and maximizing its performance.
+   - **[AI Knowledge Base Quick Start Guide](https://github.com/neomjs/neo/blob/dev/.github/AI_QUICK_START.md):** Then, follow this guide to build the local knowledge base that the AI uses to understand the project.
 
 **2. Then, just chat with your AI:**
 ```bash

.github/ISSUE/ticket-create-working-with-agents-guide.md

@@ -5,8 +5,13 @@
 
 ## Description
 
-Create a new guide, `WORKING_WITH_AGENTS.md`, to provide instructions for human developers on how to effectively interact with AI agents within this repository.
+Create a new guide, `WORKING_WITH_AGENTS.md`, to provide comprehensive instructions for human developers on how to effectively and safely collaborate with AI agents within this repository.
 
-This guide should cover two primary topics:
-1.  **Session Initiation:** How to start a session by instructing the agent to follow the rules in `AGENTS.md`.
-2.  **Error Recovery:** How to guide an agent to recover from mistakes, such as typos or getting stuck, by asking it to review its own actions.
+This guide covers several critical topics:
+1.  **Session Initiation:** How to start a session correctly by directing the agent to `AGENTS.md`.
+2.  **Error Recovery:** How to guide an agent to recover from mistakes.
+3.  **Agent Behavior:** An explanation of non-determinism and accuracy, setting the right expectations.
+4.  **The "Golden Rule":** A critical safety rule about never using "Always Allow" for file modifications, backed by security research on agentic misalignment.
+5.  **Panic Responses:** How to spot and handle destructive agent behavior.
+6.  **The Session Lifecycle:** An analogy for understanding agent context degradation over time.
+7.  **Proactive Context Management:** A best practice for knowing when to start a fresh session.