RFC: Agentic Workflow Practices for the Community

Development RFCs
1

Decision Due Date: May 31, 2026

As a community, I believe we need to collaborate on how to embrace and mitigate the impacts of AI. This goes beyond AI contributions, which has shown general positivity in this direction. AI is a tool that, with careful consideration, can be used to help enhance our community, the code we produce and ultimately the community’s use of the project. AI lowers the barrier for contribution, this can increase the burden on maintainers while providing more value to the community. This RFC is designed to continue that conversation and propose some concrete actions for us to take.

AI is a spectrum of use cases. Many open source communities are going through similar exercises to identify where it fits. This RFC is a conversation starter. I need everyone’s help and feedback to shape this for our community.

Context and Problem Statement

Contributors are already using AI tools. Our challenge as a community is not whether to permit this but how to ensure AI-assisted contributions meet the same quality bar as human contributions. How to embrace the use of AI to the greater benefit of the community as a whole.

The community discussion on AI contributions showed consensus: disclosure is good, accountability stays with the contributor, non-prescriptive norms are preferred, and there is concern about contributors submitting AI output they don’t understand.

Foreman’s multi-repo ecosystem creates steep onboarding friction. AI tooling that embeds project knowledge can lower this barrier — if the knowledge is correct and maintained. The Foreman handbook outlines how to contribute, how to review and provides institutional knowledge that AI tools can help contributors self-check against before submission, shifting quality left.

Non-goals

  • Mandating AI tool usage. Contributors who prefer not to use AI tools are equally welcome.
  • Increasing PR volume. The focus is reducing friction and improving quality, not generating more work for maintainers to review. This may happen naturally, but is not a stated goal.
  • Prescribing specific tools. Practices should work across tools that contributors want to use and can consume AI-related assets.

Proposal

Provide Agentic skills, agents and AI-built tooling as a community: shared, maintained, governed by existing practices.

  • Every contribution is judged by the review checklist inspired by the handbook, not by how it was produced. AI assistance is not a shortcut past review.
  • The contributor is accountable for every line. “The AI wrote it” is not an answer to “why does this work?”
  • Focus on AI applications that lower the barrier to quality contributions — not applications that generate more PRs for maintainers to review.
  • Context files and skills use open formats (markdown, YAML frontmatter) that work across tools. No vendor lock-in.
  • Generally useful skills, context files, and guardrails is encouraged to be contributed to the community rather than maintained privately.

Actions

The actions follow a deliberate sequence. Each phase builds capability that the next phase depends on.

  1. Context files across community repositories. Add context files (e.g. AGENTS.md) to repositories that contribute to the Foreman ecosystem (e.g. theforeman and katello GitHub organizations). These are structured developer documentation that also serves as AI context. The most basic context file to add would be an AGENTS.md. Initial context files will be contributed through a concentrated community effort; each repository’s maintainer owns ongoing maintenance if they accept it like any other code asset.

  2. AI contribution norms. Establish norms for AI-assisted contributions:

    • Git trailers (Assisted-By: <tool>) for substantial AI assistance — recommended, not required
    • Contributor accountability — you must be able to explain every change you submit
    • Require GPG or SSH signed commits by authors.

  3. Establish a shared agentic repository. Move ehelms/foreman-ai-harness (open to rename) repository and invite the community to contribute agentic assets that are re-usable.

  4. Developer documentation updates. A concentrated effort to manage the bulk of development documentation in theforeman/foreman, and dedicated specific documentation within each repository where relevant. Plugin repositories should link back to the primary documentation where necessary to help with routing and context.

Proposed Guardrails

  1. Disclosure. Recommend Assisted-By: <tool> or Co-Authored-By: <tool> trailers for substantial AI assistance. Trivial assistance (autocomplete) needs no disclosure.
  2. Accountability. The author of a PR is accountable for every line and should understand and be able to explain. Maintainers continue to be accountable for any code that is merged.
  3. Shared assets. Contribute generally useful agentic assets to foreman-ai-harness. Organization-specific or deployment-specific tooling need not be contributed.

Alternative Designs

Do nothing. Contributors are already using AI tools individually. Without shared practices, each organization and contributor develops their own norms — or none at all. Context files don’t get written. Skills don’t get shared. Quality expectations remain implicit. The likely consequences:

  • Contributors submit AI output they cannot fully explain or defend, increasing review burden.
  • Organizations build private tooling that duplicates effort and fragments the ecosystem.
  • The community has no shared position when AI-related quality concerns arise, leaving maintainers to handle them case by case.
  • Contribution volume increases without the requisite tooling to help maintainers support that increased load.

This proposal exists because doing nothing still produces outcomes — just uncoordinated ones.

Decision Outcome

To be filled after community discussion and decision.

Impacts

This proposal introduces shared AI practices and assets into the Foreman community workflow. If adopted:

  • Repositories under the theforeman and katello GitHub organizations gain context files (AGENTS.md) that serve as both developer documentation and AI context.
  • A shared repository (foreman-ai-harness) becomes the canonical location for cross-cutting agentic skills.
  • Code review processes do not change — AI-assisted contributions are held to the same bar. Where possible, review is augmented to help maintainers.
5 Likes
2

I have on my TODO this repository: GitHub - ThibautBaissac/rails_ai_agents: Specialized AI skills, agents, rules and hooks for modern Rails AI driven-development + Spec-Driven-Development kit + MCP · GitHub

Basically collected AI skills & other files from several repositories and build it from them.
Also, the 37signals shared their instructions.

We could take inspiration from it and reuse some files.

1 Like
3

Sharing for visibility: POC: Files for Agentic AI development in foremanctl.

4

Thanks Eric for starting this. I think this is a great start. I generally agree with proposed actions and guardrails. We may also want to change the repo and gh structures if it helps maintaining the context files or simplify agents the work. Everything we do to make “life easier” for agents improves the quality of life of human contributors too.

Could you please elaborate on what this brings? The reason I’m asking - this seems like additional barrier for contributors, not everyone uses GPG or has a key.

I tested this the other day on way smaller Rails app and I was very pleased. It would probably struggle with specifics of Foreman as we’re not following all Rails best practices, but as you said, we could (should) take inspiration from it.

Could Foreman benefit from an AI usage policy?
5

Does it need to be GPG signed commits? Git can also use SSH keys and that may be easier.

I’d advocate for aligning more on Rails best practices where we can.

6

I don’t want to offtopic this thread, so let me just say, these agents would likely recommend using Hotwire rather than full react UI. But I agree in principle.

7

Agreed there are exceptions. Perhaps the “where we can” should be rephrased to “where we can and where we want to”. There are many cases where we don’t follow Rails best practices just for historical reasons.

1 Like
8

I have updated to either kind of signed commit. In a world where we want to emphasize author ownership of submitted work where AI is used, and what the potential origin of that work is, signed commits help with author identity and verification. If folks can use AI to generate code, I feel confident they can figure out signing commits. As @ekohl points out, SSH keys can be used which is a standard and encouraged practice when using Github.

1 Like
9

Does this mean AI-assisted commits are expected to be unsigned? I don’t really understand what value a signed commit brings, other than identity verification.

10

While this is true, one of the non-goal is:

With SSH keys, I think the barrier is lowered significantly. Looking at the amount of signed commits today though, I think we’d need to provide some instructions so people don’t struggle and we lower the frustration of people who want to contribute.

However I still don’t fully understand what this brings compared to existing commit author name and email. Is there a concern AI could impersonate people? Is this to boost the sense of owernship for AI generated code? Or something else?

11

Thanks for sharing this, Eric. I really like the idea of expanding our compatibility to support all types of contributions. This is a great next step in creating space for AI-driven workflows without compromising our fundamental community standards and best practices.

12

IMO this is important for the open source project. It’s a shame that signatures are lost on GitHub when merging. At least you can compare the diff and see that GitHub itself signs its commits.

:+1: from me