Skip to content

[codex] clarify agent guidance ownership - #4574

Merged
turip merged 5 commits into
mainfrom
feat/agent-guidance-maintenance
Jun 26, 2026
Merged

[codex] clarify agent guidance ownership#4574
turip merged 5 commits into
mainfrom
feat/agent-guidance-maintenance

Conversation

@turip

@turip turip commented Jun 25, 2026

Copy link
Copy Markdown
Member

Summary

  • Clarify that AGENTS.md is the repo-local source of truth for universal guidance and exceptions must be confirmed.
  • Categorize AGENTS.md coding constraints into documentation, Go, TypeSpec, and generation/dependency guidance.
  • Move subsystem-specific charge adapter guidance into the charges skill and expand the samber-lo skill with standard library slices/maps and lo usage guidance.

Validation

  • Not run; documentation and skill guidance only.

Summary by CodeRabbit

  • Documentation
    • Updated billing charge adapter guidance to require transaction-aware Ent database access, with helpers using the transaction-bound context handle.
    • Refined lo guidance to prioritize Go standard library collection helpers first, with clearer imports and correctness recommendations.
    • Strengthened contributor guidance in AGENTS.md (maintenance rules, coding conventions structure, generation/dependency notes, and skill compatibility expectations).
    • Added TypeSpec style constraints for HTTP decorators like @query (required imports/using).
  • Chores
    • Improved automated review guidance for skill documentation clarity in .coderabbit.yaml, including slimmer guidance around when extra tests are unnecessary.

@coderabbitai

coderabbitai Bot commented Jun 25, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Caution

Review failed

The pull request is closed.

Warning

Ignoring CodeRabbit configuration file changes. For security, only the configuration from the base branch is applied for open source repositories.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4c0de43d-ee3a-47dc-9069-f1742eb603fd

📥 Commits

Reviewing files that changed from the base of the PR and between 007a3e5 and 19b2b69.

📒 Files selected for processing (2)
  • .agents/skills/charges/SKILL.md
  • .coderabbit.yaml

📝 Walkthrough

Walkthrough

This PR updates repository guidance in AGENTS.md and api/spec/AGENTS.md, adds review instructions for skill docs, and revises two skill docs for billing adapter transaction handling and samber-lo usage.

Changes

Repository guidance

Layer / File(s) Summary
Maintenance and skills rules
AGENTS.md
AGENTS.md updates the maintenance rules for local source-of-truth handling, exception confirmation, durable guidance wording, subtree placement, reusable workflows, and agent compatibility.
Coding and TypeSpec constraints
AGENTS.md, api/spec/AGENTS.md
AGENTS.md refactors coding conventions into documentation, Go, and generation sections, moves TypeSpec-specific guidance to api/spec/AGENTS.md, and removes the standalone TypeSpec decorator note.
Skill review instructions
.coderabbit.yaml, .agents/skills/charges/SKILL.md, .agents/skills/samber-lo/SKILL.md
.coderabbit.yaml adds review instructions for skill docs, and the two skill docs update guidance for transaction-aware charge adapters and standard-library-first samber-lo usage.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested reviewers

  • tothandras
  • chrisgacsal
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title matches the main change: clarifying ownership and scope of agent guidance across AGENTS.md and skills.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/agent-guidance-maintenance

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@turip
turip marked this pull request as ready for review June 25, 2026 19:04
@turip
turip requested a review from a team as a code owner June 25, 2026 19:04
@turip turip added the release-note/ignore Ignore this change when generating release notes label Jun 25, 2026
tothandras
tothandras previously approved these changes Jun 25, 2026
@greptile-apps

greptile-apps Bot commented Jun 25, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This PR clarifies how repository guidance should be owned and maintained. The main changes are:

  • Moves TypeSpec-specific decorator guidance into api/spec/AGENTS.md.
  • Reorganizes root AGENTS.md coding constraints into clearer sections.
  • Adds charge adapter transaction guidance to the charges skill.
  • Expands the samber-lo skill with standard library slices and maps guidance.
  • Adds review guidance for skill documentation in .coderabbit.yaml.

Confidence Score: 5/5

This looks safe to merge.

  • No blocking issues found in the changed code.

Important Files Changed

Filename Overview
AGENTS.md Clarifies root guidance ownership and reorganizes universal coding constraints.
api/spec/AGENTS.md Adds the TypeSpec HTTP decorator import guidance in the API spec subtree.
.agents/skills/charges/SKILL.md Adds transaction-aware Ent access guidance for charge adapters.
.agents/skills/samber-lo/SKILL.md Expands guidance for choosing standard library collection helpers and samber/lo.
.coderabbit.yaml Adds review instructions for durable skill documentation feedback.

Reviews (5): Last reviewed commit: "Merge branch 'main' into feat/agent-guid..." | Re-trigger Greptile

Comment thread AGENTS.md Outdated

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.agents/skills/charges/SKILL.md:
- Around line 68-71: Clarify the adapter transaction guidance so it is
actionable for helpers under openmeter/billing/charges/.../adapter: state that
shared helper functions must use the transaction-aware repo/adapter handle from
ctx rather than relying on a raw *entdb.Client being “rebound” by
TransactingRepo/TransactingRepoWithNoValue. Update the wording around the
affected helper functions and adapter rules to make it explicit that the helper
body should be wrapped with the transacting helper and access the client through
the swapped repository handle.

In @.agents/skills/samber-lo/SKILL.md:
- Around line 74-75: The guidance around using lo.Map with lo.Uniq for
slice-wide invariants should also mention that lo.Uniq only works for comparable
projected values. Update the note near the distinct-value validation pattern to
call out this compile-time constraint and point readers to lo.UniqBy when the
projected type may be a slice, map, or otherwise non-comparable, so the
recommendation stays correct and easy to apply.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 082c692c-ddd0-4db9-a9d3-45eee6fa199d

📥 Commits

Reviewing files that changed from the base of the PR and between 18e5c91 and 23bbb81.

📒 Files selected for processing (3)
  • .agents/skills/charges/SKILL.md
  • .agents/skills/samber-lo/SKILL.md
  • AGENTS.md

Comment thread .agents/skills/charges/SKILL.md
Comment thread .agents/skills/samber-lo/SKILL.md
@turip
turip requested a review from tothandras June 25, 2026 19:25
tothandras
tothandras previously approved these changes Jun 25, 2026
GAlexIHU
GAlexIHU previously approved these changes Jun 25, 2026
borosr
borosr previously approved these changes Jun 25, 2026
Signed-off-by: Peter Turi <peter.turi@openmeter.io>
@turip
turip dismissed stale reviews from borosr, GAlexIHU, and tothandras via 19b2b69 June 26, 2026 10:54
@turip
turip merged commit d30d21d into main Jun 26, 2026
23 of 24 checks passed
@turip
turip deleted the feat/agent-guidance-maintenance branch June 26, 2026 10:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

release-note/ignore Ignore this change when generating release notes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants