Hi all, I did a bit more work on this. Currently added on master but some parts are flagged as work-in-progress. A brief summary below.
Approach: humans-first. AGENTS.md and the new skills under .agents/skills/ point into a set of human-facing docs that are the authoritative source - the same pattern Grails, Micronaut, and Airflow have converged on. So most of the work has been filling out thin or missing human contributor docs. New top-level documents: - ARCHITECTURE.md - repository layout, the nine compilation phases mapped to driver classes, AST and class-generation overview, extension points, public-API package conventions. - COMPATIBILITY.md - stability tiers, what counts as breaking (including the behavioural cases japicmp doesn't catch: MetaClass dispatch, Java interop, AST shape, phase ordering), deprecation policy, how the binary-compatibility check is wired up. - GOVERNANCE.md - placeholder draft. Captures the uncontroversial parts (dev@ as authoritative, lazy consensus, vote mechanics) with five named open questions for a dev@ thread: CTR/RTC mapping by change type, wait-period figures, dependency-bump policy, etc. Existing docs: - CONTRIBUTING.md - new Tests section plus a Running-your-local-build subsection covering installGroovy and the GROOVY_HOME unset gotcha for SDKMAN. - AGENTS.md - wire-in edits linking the new human docs, a Skills section, a strengthened reformatting rule (per Jochen's input on the original thread), and the provenance trailer rewritten to reflect the ASF AI working group's emerging guidance: Assisted-by as default, Co-authored-by for human co-authors, Generated-by reserved for special cases. Link to apache.org/legal/generative-tooling.html stays authoritative. - README.adoc - one paragraph pointing at installGroovy. New AI skills under .agents/skills/: groovy-internals (compiler and runtime work) and groovy-tests (regression tests and executable AsciiDoc examples). Deferred for follow-up: slimming AGENTS.md, per-subproject AGENTS.md files for high-trap modules, a reviewer playbook for AI-assisted PRs. Comments, pushback, and corrections all welcome - especially on GOVERNANCE.md's open questions and any factual errors. Cheers, Paul. On Fri, Apr 24, 2026 at 8:47 AM Jochen Theodorou <[email protected]> wrote: > 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 > >
