From 865b3bc6a99ae1adefa2b23c9a6baac5546e5be3 Mon Sep 17 00:00:00 2001
From: Florian Egger <flo.egger@icloud.com>
Date: Fri, 21 Aug 2026 15:09:03 +0200
Subject: [PATCH] Add mandatory development workflow to AGENTS.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Enforce Understand → Plan → Wait for Approval → Implement → Validate → Review.
- Require agents to read code, load skills, and produce a plan before changing files.
- Add explicit STOP after presenting the plan until user approval.
- Define minimum validation commands and self-review checklist.
- Allow trivial fixes to skip directly to implementation, but still require validation.
---
 AGENTS.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 9bfc1f3..72bce4d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,6 +15,67 @@ Available project skills:
 
 If the requested change touches more than one skill, load all of them. If a task is ambiguous or conflicts with the local-only / privacy constraint, stop and consult the user before proceeding.
 
+## Mandatory Development Workflow
+
+All non-trivial implementation tasks follow this workflow. Trivial tasks (e.g., a single typo fix or one-line import correction) may skip straight to implementation, but they still require validation.
+
+### 1. Understand
+
+Before changing anything:
+
+- Read the relevant parts of the codebase.
+- Load all applicable skills from `.agents/skills/`.
+- Identify the schemas, modules, tests, and config that the change will touch.
+- Confirm the goal and constraints with the user if anything is unclear.
+
+**Do not modify files during this phase.**
+
+### 2. Plan
+
+Produce a concise implementation plan that includes:
+
+- What files will be created, modified, deleted, or renamed.
+- Which schemas or public interfaces change.
+- How the change fits existing tests and what new tests are needed.
+- Any risks, assumptions, or open questions.
+
+### 3. Wait for Approval
+
+**STOP after presenting the plan.**
+
+Do not create, modify, delete, or rename files until the user explicitly approves the plan.
+
+Questions and clarification are allowed during this phase.
+
+### 4. Implement
+
+Once the plan is approved:
+
+- Make the smallest changes that satisfy the approved plan.
+- Follow project conventions (schemas first, type hints, error handling, logging).
+- If implementation reveals that the approved plan is materially wrong or incomplete, **stop and explain the discrepancy** rather than silently expanding scope.
+
+### 5. Validate
+
+Run appropriate tests and checks. At minimum:
+
+- `python -m pytest tests/`
+- `ruff check src tests`
+- `mypy src/odoo_ocr --ignore-missing-imports --strict` (if feasible for the change)
+
+Fix issues caused by the change. Report any pre-existing failures clearly.
+
+### 6. Review
+
+Before finishing, review your own changes:
+
+- Does the code match the approved plan?
+- Are there unintended changes or debug code left behind?
+- Are tests meaningful and not just mocks of themselves?
+- Would the next agent understand what you did?
+
+Load the `review` skill and use its checklist for any non-trivial change.
+
 ## Project Goal
 
 Build a Python application that: