Project Setup for the 🤖 Agent Workflow Protocol

The Agent Workflow Protocol is a standardized way to interact with autonomous AI coding assistants (like Google Code Assist, Cursor, Cline, etc.). It transforms chaotic, unpredictable code generation into a structured engineering process with mandatory planning, task breakdowns, and automated documentation.

The core principle of this protocol is Human-in-the-Loop. The AI agent is strictly forbidden from writing application code without explicit architectural and task approval from the developer.

Step 1. Setting Up the Directory Structure

To prevent the AI agent from cluttering your project root and to maintain a history of its architectural decisions, you need to create a dedicated documentation directory.

Create the following structure in your project's root folder:

your-project/
└── docs/
    └── agent/
        └── features/    # The AI will create subfolders for each feature here

💡 Why is this necessary? Every new feature (e.g., google_auth, checkout_tax_fix) will get its own isolated folder here containing the plan (01_PLAN.md), the task list (02_TASKS.md), and the execution log (03_WALKTHROUGH.md).

Step 2. Creating the System Prompt

The AI agent requires strict behavioral boundaries. You need to create a configuration file in the root of your project. (Note: The filename depends on your IDE—commonly AGENT.md, GEMINI.md, CLAUDE.md, .cursorrules, or similar).

Paste the Standard Agent Workflow Protocol Template into this file. Make sure it includes the strict 3-Phase stop-and-wait instructions.

Step 3. Defining the Project-Specific Context (Critical!)

The AI needs to know how your specific team writes code, especially for rigid e-commerce platforms.

You must manually fill out the ## 🛠️ Project-Specific Context section at the bottom of the system prompt.

Below are examples of how to fill this out for popular e-commerce platforms. Pick the one relevant to your project or adapt it:

Example A: Magento 2 (Adobe Commerce)

## 🛠️ Project-Specific Context
- **Platform:** Magento 2.4.x, PHP 8.2, MySQL, Knockout.js.
- **Strict Architecture Rules:**
  - **NEVER** modify core files in the `vendor/` directory. All customizations must be done via custom modules in `app/code/` or theme files in `app/design/`.
  - Prefer using **Plugins (Interceptors)** (before, after, around) over Preferences for class overrides to avoid conflicts.
  - Use **ViewModels** instead of extending Block classes to pass data to templates (`.phtml`).
  - Use Declarative Schema (`db_schema.xml`) for database modifications; NEVER use legacy install/upgrade scripts.
  - Strict typing in PHP is mandatory (`declare(strict_types=1);`).
  - Always use dependency injection (`__construct`) to instantiate objects; avoid using `ObjectManager` directly.

Example B: PrestaShop (8.x)

## 🛠️ Project-Specific Context
- **Platform:** PrestaShop 8.x, PHP 8.1, Symfony 4.4+, Smarty (Front Office), Twig (Back Office).
- **Strict Architecture Rules:**
  - **NEVER** modify core files directly. Use Overrides only as a last resort if Hooks are not sufficient.
  - Rely heavily on **Hooks** (`registerHook`) to inject content or logic into the Front Office and Back Office.
  - For custom Back Office pages, strictly use modern Symfony routing, controllers, and Twig templates instead of legacy AdminControllers.
  - Always use PrestaShop's `Db::getInstance()` and `ObjectModel` classes for database interactions; prevent SQL injection by using `pSQL()`.

Example C: WooCommerce (WordPress)

## 🛠️ Project-Specific Context
- **Platform:** WordPress 6.x, WooCommerce 8.x, PHP 8.0+.
- **Strict Architecture Rules:**
  - **NEVER** modify WordPress core files or WooCommerce plugin files directly.
  - Heavily prioritize using `add_action()` and `add_filter()` to modify WooCommerce behavior (e.g., checkout fields, cart logic).
  - If a template override is absolutely necessary, copy the template from `plugins/woocommerce/templates/` to the `woocommerce/` folder inside the active child theme.
  - Prefix all custom functions, classes, and database options with the project prefix.
  - Always sanitize, escape, and validate user input using native WP functions (`sanitize_text_field`, `esc_html`).

Step 4. Developer Cheat Sheet (Daily Workflow)

Once the project is set up, working with the AI looks like this:

1. Start: Open the AI Agent chat in your IDE and state your task: "Implement a custom VAT field in the checkout according to the AGENT_WORKFLOW."
2. Phase 1 (Planning): The agent will analyze the code, create 01_PLAN.md, and stop.
   • Action: Review the plan. If you have changes, tell the agent in the chat to update it. If it looks good, type "APPROVED".
3. Phase 2 (Tasks): The agent will break the plan down into a checklist in 02_TASKS.md and stop.
   • Action: Review the steps and type "APPROVED".
4. Phase 3 (Execution): The agent will start writing the actual code step-by-step, logging its progress and file changes in 03_WALKTHROUGH.md.