From 109deaaf65902e17902237164045d11da6c91abb Mon Sep 17 00:00:00 2001
From: NagyVikt <nagy.viktordp@gmail.com>
Date: Wed, 22 Apr 2026 21:45:38 +0200
Subject: [PATCH] Keep agent execution guidance fast and phase-based

Add a token-efficient execution contract near the top of AGENTS.md so future runs start with bounded planning, grouped execution, compact reporting, and minimal re-reading.

Constraint: Preserve existing Guardex and OpenSpec workflow rules
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep future execution guidance additive here unless the repo-wide workflow contract changes
Tested: git diff --check -- AGENTS.md; rg -n '^## Objective$|^## Token-Efficient Execution$|^### Planning$|^### Reporting$|^### Verification$' AGENTS.md
Not-tested: Full repo docs lint or markdown style automation
---
 AGENTS.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 21192bcf..bad0d365 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,6 +6,58 @@ This document is the agent contract for this repo. It applies identically to Cod
 
 When writing complex features or significant refactors, use an ExecPlan (as described in `.agent/PLANS.md`) from design to implementation.
 
+## Objective
+
+- Optimize for task completion with low token use.
+- Prefer phase-based execution over conversational micro-steps.
+
+## Token-Efficient Execution
+
+### Planning
+
+- Start each task with a plan of at most 4 bullets.
+- Work in phases:
+  1. minimal inspection
+  2. grouped edits or grouped repo actions
+  3. focused verification
+  4. compact summary
+- Treat obvious follow-on actions as part of the active phase; do not stop for tiny internal checkpoints.
+- If context grows or the session becomes fragmented, write a short working summary and continue from it.
+
+### Token Discipline
+
+- Do not re-read the same file, line range, or command output unless the file changed or new evidence requires it.
+- Prefer targeted reads: `rg`, `head`, `tail`, `git diff`, and exact line ranges.
+- Keep command output compact and relevant.
+- Avoid repeated status checks unless something changed.
+
+### Command Discipline
+
+- Batch related shell commands whenever safe.
+- Prefer one-shot non-interactive commands, scripts, or exact invocations over interactive loops or repeated stdin driving.
+- For diagnosis, gather the relevant evidence in one pass, then summarize once.
+
+### Git And PR Workflow
+
+- Treat local git and PR work as one bounded phase when possible: inspect status, stage intended files, commit, push, and check PR or CI.
+- Do not narrate every trivial git step; summarize branch, commit, PR, and CI state once per phase.
+
+### Reporting
+
+- Use this format:
+  1. Plan
+  2. Actions taken
+  3. Verification
+  4. Result
+- Keep reports concise and focused on blockers, material changes, and verification outcomes.
+
+### Verification
+
+- Always verify before finalizing.
+- Choose the smallest verification that meaningfully proves the change.
+- Do not run redundant checks.
+- Pause only for destructive actions, ambiguous intent, missing credentials or access, or conflicting evidence.
+
 ## Environment
 
 - Python: .venv/bin/python (uv, CPython 3.13.3)