feat: add workflow rules to AGENTS.md for test ordering, template usage, and self-improvement flow

AGENTS.md

@@ -111,10 +111,16 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow. Key rules:
 - Open an Issue before starting work
 - Branch from `main`: `feat/`, `fix/`, or `chore/` prefix
 - Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `chore:` — no scopes for now
+- AGENTS.md improvements are `feat:`, not `chore:` — they add value to the agent workflow
 - Rebase on `main` before PR — linear history, no merge commits
 - One logical change per PR — keep it atomic
 - CI must be green (build, tests, schema validation, Trivy, Gitleaks)
+- Always read the repository templates before creating issues or PRs:
+  - Issues: `.github/ISSUE_TEMPLATE/` — use the matching template and fill in all required fields
+  - PRs: `.github/PULL_REQUEST_TEMPLATE.md` — follow the structure exactly, do not improvise
 - Do **not** use `git push --force` — use `--force-with-lease`
+- When the user corrects a mistake, note it immediately so the insight is not lost — see [Self-Improvement](#self-improvement)
+- When the workflow is complete, review any noted corrections and propose rule updates if warranted
 
 ## Bug Workflow (mandatory)
 
@@ -165,16 +171,34 @@ Run the full test suite before committing:
 mvn test
 ```
 
+**Ordering:**
+1. Write the tests first — only modify files under `src/test/` (and `src/test/resources/`)
+2. Run `mvn test` and confirm the new tests **fail** (proving the bug exists)
+3. Only then implement the fix in `src/main/`
+4. Run `mvn test` again and confirm all tests **pass**
+
+Do not edit production code (`src/main/`) and test code (`src/test/`) in the same phase.
+
 All existing tests must stay green. If a pre-existing test fails, investigate before touching it.
 
+When the user corrects a workflow step, note it immediately so the insight is not lost — see [Self-Improvement](#self-improvement).
+
+### 4. Review noted corrections
+
+Once the fix is merged (or the PR is open and CI is green), review any corrections the user made during the workflow and evaluate them against the [Self-Improvement](#self-improvement) criteria. Propose rule updates only at this point.
+
 ## Self-Improvement
 
-When a user corrects agent-generated code, evaluate whether the correction should become a new rule in this file. Suggest an AGENTS.md update **only** when all three conditions are met:
+When a user corrects agent-generated code or workflow, **note it immediately** so the insight is not lost, then **resume the current workflow** without interruption. Do not propose a rule change mid-workflow — wait until the workflow is complete (see Bug Workflow Step 4, Contribution Workflow end-of-list).
+
+Suggest an AGENTS.md update **only** when all three conditions are met:
 
-1. The corrected code was **generated by the agent** (not pre-existing code being refactored)
-2. The correction is **structural** — it targets a convention, pattern, or style choice (e.g. visibility, naming, test design) — not a one-off logic bug or domain-specific mistake
+1. The corrected code or action was **generated by the agent** (not pre-existing code being refactored)
+2. The correction is **structural** — it targets a convention, pattern, or style choice (e.g. visibility, naming, test design, workflow step) — not a one-off logic bug or domain-specific mistake
 3. The correction is **generalizable** — the same mistake could plausibly recur in a different file or context
 
 When all three conditions are met, propose the specific Do/Don't entry and the section it belongs to. Do not apply it — let the user decide.
 
+When the conditions are **not** met, do not propose anything — avoid noise. Most corrections are one-off and do not need a rule.
+
 For reference, the Test Writing Rules and Method Visibility sections in this file were both added through this process.