chore(agents): clarify workflow expectations

[Liam-Deacon]

Summary by Sourcery

Documentation:

• Refine AGENTS.md to more clearly describe required workflows for branches, testing, pre-commit usage, PR descriptions, and actionable issue reporting.

[sourcery-ai]

Reviewer's Guide

Updates AGENTS.md to more explicitly define the required contributor workflow, tightening wording around worktrees, pre-commit usage, testing expectations, PR descriptions, and issue hygiene while keeping the process the same in practice.

Flow diagram for the required contributor workflow with pre-commit and tests

flowchart TD
  Start["Start new task or issue"] --> Worktree["Create git worktree and branch for this task"]
  Worktree --> Implement["Implement small, focused changes"]

  Implement --> PreCommit["Run pre-commit hooks (format/validate)"]
  PreCommit --> Tests["Run targeted tests (unit/integration/system)"]

  Tests --> TestsExist{Tests exist for affected area?}
  TestsExist -- Yes --> EvaluateTests{Tests pass?}
  TestsExist -- No --> AddTests["Add deterministic tests where practical"] --> EvaluateTests

  EvaluateTests -- No --> FixIssues["Fix issues and repeat pre-commit + tests"] --> PreCommit
  EvaluateTests -- Yes --> Commit["Create Conventional Commit with meaningful scope"]

  Commit --> Push["Push branch to origin"]
  Push --> PR["Open PR via gh with required sections"]

  PR --> PRContent["Include: problem, solution, testing, links, follow-ups"]
  PRContent --> Review["Review and iterate based on feedback"]
  Review --> Ready{All checks and reviews green?}

  Ready -- No --> Implement
  Ready -- Yes --> Merge["Merge PR and close related issues if appropriate"]

Loading

File-Level Changes

Change	Details	Files
Clarify and strengthen the core contributor commitments and expectations around worktrees, pre-commit, testing, and documentation.	Renames the "Golden rules" section to "Core commitments" and reframes the opening paragraphs to emphasize this document as the authoritative guide. Expands each numbered guideline to describe required behaviors (isolated worktrees, mandatory pre-commit before push, required surface-area testing, root-cause focus, avoiding generated artifacts, and documenting PR context).	AGENTS.md
Tighten workflow instructions for commits, testing, and pull requests to emphasize order of operations and required content.	Refines branch prefix descriptions to clarify when to use chore vs feat. Clarifies Conventional Commit expectations, encouraging scopes and concise commit bodies that explain what/why/how-tested and follow-ups. Makes pre-commit explicitly run before project tests, and describes the combined requirement of hooks plus targeted tests, including expectations for adding deterministic tests when needed. Adjusts PR description requirements to stress coverage of motivation, solution, testing, links (issues + permalinks), and follow-up checklists.	AGENTS.md
Polish terminology and wording for issues, repository hygiene, and escalation path without changing the underlying process.	Simplifies and tightens wording in the issues section (environment, repro steps, expected vs actual, logs/errors, proposed direction). Clarifies repository hygiene guidance to avoid committing build/config outputs and to prefer ignore rules over generated content, while discouraging large refactors in one PR. Minor wording change in the escalation path section while keeping the multi-step split of large initiatives the same.	AGENTS.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey there - I've reviewed your changes - here's some feedback:

• The reference to 'Qt6' in the escalation section was changed to 'QT6'; consider reverting to the standard 'Qt6' capitalization to match the project and upstream naming.
• The phrase 'pre-commit + tests = required' is a bit informal for a normative requirement; consider rephrasing to something more explicit like 'Running both pre-commit and the relevant tests is required before opening a PR.'

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The reference to 'Qt6' in the escalation section was changed to 'QT6'; consider reverting to the standard 'Qt6' capitalization to match the project and upstream naming.
- The phrase 'pre-commit + tests = required' is a bit informal for a normative requirement; consider rephrasing to something more explicit like 'Running both pre-commit and the relevant tests is required before opening a PR.'

## Individual Comments

### Comment 1
<location> `AGENTS.md:116` </location>
<code_context>
 ## Suggested escalation path

-For larger initiatives (Qt6 migration, NR removal, packaging automation), split work into:
+For large initiatives (QT6 migration, NR removal, packaging automation), split work into:

 ```
</code_context>

<issue_to_address>
**suggestion (typo):** Consider correcting "QT6" to the conventional "Qt6" spelling.

Using the standard "Qt" capitalization here will keep terminology consistent with the framework’s official naming.

```suggestion
For large initiatives (Qt6 migration, NR removal, packaging automation), split work into:
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

suggestion (typo): Consider correcting "QT6" to the conventional "Qt6" spelling.

Using the standard "Qt" capitalization here will keep terminology consistent with the framework’s official naming.

Suggested change

	For large initiatives (QT6 migration, NR removal, packaging automation), split work into:
	For large initiatives (Qt6 migration, NR removal, packaging automation), split work into:

[codacy-production]

Codacy's Analysis Summary

1 new issue (≤ 0 issue)
0 new security issue

Review Pull Request in Codacy →

✨ AI Reviewer available: add the codacy-review label to get contextual insights without leaving GitHub.