Re: Initial AGENTS.md

On 4/23/26 17:21, Jochen Theodorou wrote:
> On 4/23/26 03:30, Paul King wrote:
>> I committed one:
>>
>> https://github.com/apache/groovy/blob/master/AGENTS.md <https:// 
>> github.com/apache/groovy/blob/master/AGENTS.md>
>>
>> But please make suggestions if you spot anything that should be 
>> included initially.
> You have it kind of in there, but I would add to not reformat code and 
> keep the formatting style of the file for new and changed code.
> 
> There is quite a bit more, but I first have to ask for permission to use 
> that.


we  add things like this for the workflow

Global Override
     Always state assumptions explicitly before substantial execution.
     Always ask clarifying questions in multi-answer format with 
suggested/recommended answers before non-trivial changes.
     Keep rationale concise, matter of fact: explain decisions briefly 
(assumptions, tradeoffs, risks, verification), not hidden or verbose 
reasoning.
     Treat substantial execution as any task beyond a typo-only or 
comment-only trivial edit, including any file edit, mutating command, 
commit, plan creation, or multi-file investigation.

Hard Stop Gate (Before Edits)

Do not edit files, run mutating commands, create plans, or create 
commits until:

     assumptions are stated
     multi-answer clarifications are asked
     user answers/approves direction

Only typo-only or comment-only trivial edits may bypass this gate.

Core Workflow

     Plan first for non-trivial tasks (objectives, steps, key commands, 
estimate XS/S/M/L).
     Ask clarifying questions and a final refinement question on goal, 
scope, or success criteria.
     Execute with traceability (list key files/commands/decisions).
     Run quality gate for runtime-impacting changes: lint, tests, 
self-review.
     Report what was run and what was skipped (with reason).

Kickoff Checklist (Before Any Tool Call)

     Assumptions stated explicitly
     Verification questions asked (with suggested answers)
     Discovery questions asked (multi-answer with recommendation)
     Refinement question asked
     User confirmation received

If any item is unchecked, execution must pause.
Security And Architecture Guardrails

     Preserve security posture (input validation, authn/authz, secret 
handling, safe logging).
     Ask before introducing potential security/performance/design 
regressions.

Co-Author Calculation (At Commit Time)

     Maintain agent-usage.log during task execution, one line per agent 
identity:
         Name <email>
     At commit time, append unique trailers derived from the log:
         sort -u agent-usage.log | sed 's/^/Co-authored-by: /'
     Do not add co-authors for agents not used in the current task.

Transparency Additions

     Add an ## Agent Trace section to PR descriptions:
         agents used
         files touched per agent
         checks run per agent
     Keep agent-usage.log under .gitignore, but attach a summarized 
trace in PR description.
     Add commit footers for provenance:
         Generated-by: <agent/tool>
         Reviewed-by: <human or agent>
     Add a CI check that rejects commits missing:
         valid Conventional Commits header
         required JIRA ID policy
         required co-author/provenance trailers
     Create docs/agent-transparency.md with examples and policy exceptions.


Then Commit and PR conventions, a Quality gate (like pass all tests, do 
not disable tests)


Things like the guardrails in the other post are also useful. I am not 
saying we *need* all that, just giving some food for thought

bye Jochen