On 4/14/26 16:31, Sylvain Bauza wrote:

Le mar. 14 avr. 2026 à 12:59, Sean Mooney <smooney@redhat.com <mailto:smooney@redhat.com>> a écrit :

Hi all,

I wanted to share a lightweight, cross-project approach to supporting AI coding assistants in OpenStack repositories and get community feedback before the PTG next week.

Two early implementations are available for review:

   Nova (more complete): https://review.opendev.org/c/openstack/nova/+/984540 <https:// review.opendev.org/c/openstack/nova/+/984540>

   Watcher Dashboard (earlier iteration, needs further refinement): https://review.opendev.org/c/openstack/watcher-dashboard/+/983334 <https://review.opendev.org/c/openstack/watcher-dashboard/+/983334>

FWIW, (but you already know), I also wrote some POC demonstrating some workflows for Nova here https://github.com/sbauza/openstack-agentic- workflows <https://github.com/sbauza/openstack-agentic-workflows> Some of the prose is about creating a knowledge doc for Nova [1] and I also added some rules for LLMs [2]

All of those files could also be in the upstream nova repository as well but we'll discuss that on the Nova PTG [3]

Please note that some of those files look specific to downstream, like backporting workflows, and should not be placed into upstream repositories. But triage process may depend on the issues tracker system in use (launchpad vs jira/bugzilla). Some of them may be expecting a cross-project expertise, which we should avoid duplicating for the involved projects. To simplify maintenance of those, there should be an **only place** for each project where its tribal knowledge and expertise will be stored as rules, workflows and other sources of knowledge, and where from other projects may consume it by a reference. This is irrelevant to the form of consumption of it (short-lived agent session, long-lived subagents, personas or the like). I drafted some ideas around that (AI generated, but thoroughly reviewed and edited by me), and wanted to share that repository [0] with the community - as an example of such a framework for external knowledge consumption via MCP servers and its native search() capabilities. [0] https://github.com/bogdando/opendev-agents/blob/main/README.md

[1] https://github.com/sbauza/openstack-agentic-workflows/blob/main/ knowledge/nova.md <https://github.com/sbauza/openstack-agentic- workflows/blob/main/knowledge/nova.md> [2] https://github.com/sbauza/openstack-agentic-workflows/blob/main/ rules.md <https://github.com/sbauza/openstack-agentic-workflows/blob/ main/rules.md> [3] https://etherpad.opendev.org/p/nova-2026.2-ptg#L316 <https:// etherpad.opendev.org/p/nova-2026.2-ptg#L316>

Background ----------

AI coding assistants have become part of many contributors and reviewers day-to-day workflow. Most tools support some form of context file (AGENTS.md, CLAUDE.md, .cursorrules, Copilot instructions, etc.) that you drop at the repository root to guide agent behaviour. Without one, agents fall back to generic assumptions that do not match our projects' conventions: they reach for pytest instead of stestr, propose GitHub PRs instead of Gerrit reviews, or omit the Generated-By / Assisted-By trailers required by the OpenInfra Foundation AI policy [1].

The risk of doing nothing is that every contributor ends up maintaining their own private prompt file, those files diverge, and the community gets no shared benefit from what contributors learn and reviewers cant have a way to enforce there expectations automatically before they are asked to review.

Philosophy: tell the agent to RTFM ----------------------------------

The core idea is to keep the scaffold minimal. If a convention must be followed, it should be documented in human-readable prose that agents can find through normal file exploration, not in a separate AI-curated summary that can drift from the authoritative source.

In practice:

   - AGENTS.md is a routing index, not a rulebook. It points to      HACKING.rst, the contributor docs, tox.ini, and other canonical      sources rather than duplicating them.

   - Agents are expected to read the actual project documentation, the      same way a new human contributor would.

   - The file is kept short (under 100 lines), which also keeps it      token-efficient when injected into agent context windows.

The per-project content is whatever would genuinely mislead an agent without it: tooling gotchas, workflow specifics, routing pointers to where the real rules live. The structure and philosophy are shared across projects.

What each project adds -----------------------

The scaffold is a small, consistent set of files:

1. AGENTS.md: the routing index. Content is project-specific; the role     and conventions are shared. Kept under 100 lines.

2. CLAUDE.md: a symlink to AGENTS.md. Not all tools support the same     filename: most support AGENTS.md natively, but some (including     Claude Code) look for CLAUDE.md instead. The symlink means both     filenames resolve to the same content with nothing to keep in sync.

3. ai/: a gitignored directory for agent session memory, plans, scratch     notes, and ephemeral files. Agents are directed to prefer ai/tmp/     over the system temp directory so that all agent file I/O stays     inside the repo tree, visible to the developer and sandboxed from     shared system space. Only ai/.keep is committed.

4. A contributor doc (e.g. agentic-coding.rst) documenting the     conventions and the AGENTS.md philosophy. This is what agents read     when they follow the routing pointer; the project's own docs carry     the detail.

5. Optionally, a repo-overview doc with a terse map of the repository     layout, primarily for human orientation.

The Nova review is the more complete reference implementation. The Watcher Dashboard review is an earlier iteration that still needs refinement but shows the approach applied to a different project.

Intentional scope -----------------

This proposal is limited to the scaffolding layer: AGENTS.md routing, the ai/ session directory, and the contributor docs. It does not propose in-repo skills, subagents, or shared prompt libraries.

I think the community needs more time to learn how to build and maintain such tools effectively before we standardise on anything. What this scaffold does is enforce project preferences at the routing level while leaving contributors free to experiment locally with whatever agent tooling works for them.

Vendor neutrality -----------------

The scaffold is tool-agnostic. AGENTS.md [2] is the emerging cross-tool standard, now stewarded by the Agentic AI Foundation under the Linux Foundation, with native support across Cursor, Codex, Aider, and others. Tools that do not support AGENTS.md typically support CLAUDE.md instead, which is why the symlink covers both cases with a single file to maintain. No tool names appear in the committed documentation; examples use generic placeholders. Any contributor, with any AI assistant, should get the same benefit.

The contributor doc also documents how to express the Foundation AI policy [1] as standard git footers, keeping disclosure information in a consistent, machine-readable location without adding new obligations.

Discussion questions for the PTG and the list ---------------------------------------------

1. Does this philosophy seem right: minimal scaffold, agents read the     actual project docs? Or should projects invest in richer inline     context files?

as I said, I'd prefer to have more context files for each of the project, because the AGENTS.md file could be pretty large if we don't split it.

2. Is there value in the TC providing a cross-project baseline so     projects do not each start from scratch? The openstack/hacking     repository, which already owns shared coding standards, seems like a     natural home for a baseline AGENTS.md that projects extend.     Im Interested in views on that vs a new repo or just good old     copy pasta

With my TC hat, I could say I'd prefer each of the projects have a AGENTS.md if they *want* but I see your point.

3. Are there common gotchas shared across OpenStack projects (Gerrit     workflow, DCO, stestr, pbr) that belong in such a baseline rather     than being repeated per-repo?

I think a shared PTG topic or including it in similar planed topics could be a good way to facilitate wider discussion. i had planed to bring it up in the nova/watcher/cyborg sessions if there was time to see how open each team was to this proposal. Feedback on the reviews or on this thread is equally welcome.

FWIW, we already have a TC topic for it in https://etherpad.opendev.org/ p/apr2026-ptg-os-tc#L34 <https://etherpad.opendev.org/p/apr2026-ptg-os- tc#L34> so we will discuss that anyway.

Thanks for discussing it. -Sylvain

regards sean [1] https://openinfra.org/legal/ai-policy <https://openinfra.org/ legal/ai-policy> [2] https://agents.md/ <https://agents.md/> (Agentic AI Foundation / Linux Foundation)

ps yes this has been proofread by ai which is why its in english with punctuation not sean speak ... mostly

-- Best regards, Bogdan Dobrelya, Irc/Slack #bogdando

On Wed, Apr 15, 2026 at 11:30 PM Sylvain Bauza <sbauza@redhat.com> wrote:

For sure, *skills* are for end-users and possibly different for each of us. *Knowledge data* and *personas (subagents)*, tho, can be shared between users and LLMs can use them upstream.

I think there's an interesting point there which I don't think is the point you're trying to make... With Claude at least, skills can easily live outside of a specific project repository. For example, there could be a git repo of "recommended skills for OpenStack development" that people check out to their ~/.claude/ **if they wanted to**, which might improve the quality of their AI assisted work. That's also likely to have fewer collisions than a single shared AGENTS.md file, and also doesn't "pollute" the main repository with things that some people clearly not ready to see. The nice bit is, because they're just markdown files, the same documentation is actually helpful to unassisted humans too. We're talking effectively about a set of markdown files that state things like: * this is what a good release note looks like * this is what a good sqlalchemy migration looks like * this is how to write a new tempest test * this is how _we_ write unit tests, which is definitely not the default * et cetera, et cetera I have also had a disturbingly large amount of luck with agent-assisted debugging. I have handed Claude the logs for broken Kolla-Ansible deployed clusters, and it churns for a bit and then tells me I have some subtle Neutron setting wrong. It was also correct and saved me hours. I've been using a debug bundle collection script in my private CI, but I have also had a lot of success with giving the agent access to log aggregation via loki or equivalent. That is, I think there are also useful **operator** agent skills out there if we looked for them. Would OpenStack accept a new project that delivers an "agent skills" repository? Michael

On Thu, 2026-04-16 at 09:11 +1000, Michael Still wrote:

On Wed, Apr 15, 2026 at 11:30 PM Sylvain Bauza <sbauza@redhat.com> wrote:

...

For sure, *skills* are for end-users and possibly different for each of us.  *Knowledge data* and *personas (subagents)*, tho, can be shared between users and LLMs can use them upstream.

I think there's an interesting point there which I don't think is the point you're trying to make...

With Claude at least, skills can easily live outside of a specific project repository. For example, there could be a git repo of "recommended skills for OpenStack development" that people check out to their ~/.claude/ **if they wanted to**, which might improve the quality of their AI assisted work. That's also likely to have fewer collisions than a single shared AGENTS.md file, and also doesn't "pollute" the main repository with things that some people clearly not ready to see.

The nice bit is, because they're just markdown files, the same documentation is actually helpful to unassisted humans too. We're talking effectively about a set of markdown files that state things like:

* this is what a good release note looks like * this is what a good sqlalchemy migration looks like * this is how to write a new tempest test * this is how _we_ write unit tests, which is definitely not the default * et cetera, et cetera

I have also had a disturbingly large amount of luck with agent- assisted debugging. I have handed Claude the logs for broken Kolla- Ansible deployed clusters, and it churns for a bit and then tells me I have some subtle Neutron setting wrong. It was also correct and saved me hours. I've been using a debug bundle collection script in my private CI, but I have also had a lot of success with giving the agent access to log aggregation via loki or equivalent. That is, I think there are also useful **operator** agent skills out there if we looked for them.

Would OpenStack accept a new project that delivers an "agent skills" repository?

At the risk of starting a +1 pile on, I also feel a separate repository would make a lot of sense. Such a repo could/should have a large set of "cores" to help represent each project (note: they don't need to be existing cores: ops and other end users should be represented too). It would be very easy to refer to this from a per-project AGENTS.md and would avoid this information getting siloed in each project. I've also had success in hierarchial AGENTS.md placement: ❯ tree ../ -L 1 openstack ├── agentsmd ├── AGENTS.md ├── aodh ├── ... └── zuul-jobs Stephen

Michael 

On 16/04/2026 10:34, Sylvain Bauza wrote:

Le jeu. 16 avr. 2026 à 11:04, Stephen Finucane <stephenfin@redhat.com> a écrit :

On Thu, 2026-04-16 at 09:11 +1000, Michael Still wrote:

...

On Wed, Apr 15, 2026 at 11:30 PM Sylvain Bauza <sbauza@redhat.com> wrote:

...

For sure, *skills* are for end-users and possibly different for each of us. *Knowledge data* and *personas (subagents)*, tho, can be shared between users and LLMs can use them upstream.

I think there's an interesting point there which I don't think is the point you're trying to make...

With Claude at least, skills can easily live outside of a specific project repository. For example, there could be a git repo of "recommended skills for OpenStack development" that people check out to their ~/.claude/ **if they wanted to**, which might improve the quality of their AI assisted work. That's also likely to have fewer collisions than a single shared AGENTS.md file, and also doesn't "pollute" the main repository with things that some people clearly not ready to see.

The nice bit is, because they're just markdown files, the same documentation is actually helpful to unassisted humans too. We're talking effectively about a set of markdown files that state things like:

* this is what a good release note looks like * this is what a good sqlalchemy migration looks like * this is how to write a new tempest test * this is how _we_ write unit tests, which is definitely not the default * et cetera, et cetera

I have also had a disturbingly large amount of luck with agent-assisted debugging. I have handed Claude the logs for broken Kolla-Ansible deployed clusters, and it churns for a bit and then tells me I have some subtle Neutron setting wrong. It was also correct and saved me hours. I've been using a debug bundle collection script in my private CI, but I have also had a lot of success with giving the agent access to log aggregation via loki or equivalent. That is, I think there are also useful **operator** agent skills out there if we looked for them.

Would OpenStack accept a new project that delivers an "agent skills" repository?

At the risk of starting a +1 pile on, I also feel a separate repository would make a lot of sense. Such a repo could/should have a large set of "cores" to help represent each project (note: they don't need to be existing cores: ops and other end users should be represented too). It would be very easy to refer to this from a per-project AGENTS.md and would avoid this information getting siloed in each project. I've also had success in hierarchial AGENTS.md placement:

❯ tree ../ -L 1

openstack

├── agentsmd

├── AGENTS.md

├── aodh

├── ...

└── zuul-jobs

What do people think about me proposing my repository to the x namespace then ?

my main concern with that is that there are several diffent repos that diffent folks have that could act as a baseline so you coudl do that but so coudl i or any of the other pocs. tharther then selecting and blessing one as a base line i think it would be better to start form an empty repo and build it up with a group of intersted people i started building https://github.com/SeanMooney/openstack-ai-style-guide in june with the hope fo evenraully "upstreaming it" to an opendev or openstack repo evrually in some form. i.e. import or select parts https://github.com/sbauza/openstack-agentic-workflows/ does have many of the same element so we are derfintly not that divergent already which is nice but i think both repo have content that likely is not requried for a shared comuntiy repo. for example *jira-issue-triage* <https://github.com/sbauza/openstack-agentic-workflows/blob/main/workflows/jira-issue-triage> and *gerrit-to-gitlab* <https://github.com/sbauza/openstack-agentic-workflows/blob/main/workflows/gerrit-to-gitlab> are not relevent to upstram even if they could be for our downstream so should not be incldued my third party ci config/jobs is not relevent to the comunity either (although we could perhspa build a review job together eventually if there was interst in that) while i hevially use subagents today https://github.com/SeanMooney/openstack-ai-style-guide/tree/master/agents that is becuase i started this repo before skill exists and subagents are less portabel then skills. i used them because at the time the option was a subagent or a slash command and subagents had the benift of havign indepent context and the ablity to use diffent modeld per agent skill work in more tools, while they dont use seperate context that is actully ok in many cases. there are also some layout decisions we would likely want to make such as prepare the repo as marketplace/plugin for tools that support that. https://code.claude.com/docs/en/plugin-marketplaces https://docs.factory.ai/cli/configuration/plugins#claude-code-compatibility opencode are stilll discing this https://github.com/anomalyco/opencode/issues/7467 the agentskill comunity that run skills.md are also proposing standaristign a venfor nual location for this |.agents/skills| https://github.com/agentskills/agentskills/issues/15 https://github.com/anomalyco/opencode/issues/10986 which is related to https://github.com/agentskills/agentskills/issues/27 this space is evolving and because of that i was advocating for not trying to have these in tree in every repo until clear portable standards emerge and are adopted it will be much similar for use to adapt these skills/agents/rules as the winner emerge if its in one repo. i.e. openstack/ai-tools or whatever we settle on.

Stephen

...

Michael

On 16/04/2026 13:39, Sylvain Bauza wrote:

Le jeu. 16 avr. 2026 à 13:46, Sean Mooney <smooney@redhat.com> a écrit :

On 16/04/2026 10:34, Sylvain Bauza wrote: > > > Le jeu. 16 avr. 2026 à 11:04, Stephen Finucane <stephenfin@redhat.com> > a écrit : > >     On Thu, 2026-04-16 at 09:11 +1000, Michael Still wrote: >>     On Wed, Apr 15, 2026 at 11:30 PM Sylvain Bauza >>     <sbauza@redhat.com> wrote: >>> >>>     For sure, *skills* are for end-users and possibly different for >>>     each of us. >>>     *Knowledge data* and *personas (subagents)*, tho, can be shared >>>     between users and LLMs can use them upstream. >>> >> >>     I think there's an interesting point there which I don't think is >>     the point you're trying to make... >> >>     With Claude at least, skills can easily live outside of a >>     specific project repository. For example, there could be a git >>     repo of "recommended skills for OpenStack development" that >>     people check out to their ~/.claude/ **if they wanted to**, which >>     might improve the quality of their AI assisted work. That's also >>     likely to have fewer collisions than a single shared AGENTS.md >>     file, and also doesn't "pollute" the main repository with things >>     that some people clearly not ready to see. >> >>     The nice bit is, because they're just markdown files, the same >>     documentation is actually helpful to unassisted humans too. We're >>     talking effectively about a set of markdown files that state >>     things like: >> >>     * this is what a good release note looks like >>     * this is what a good sqlalchemy migration looks like >>     * this is how to write a new tempest test >>     * this is how _we_ write unit tests, which is definitely not the >>     default >>     * et cetera, et cetera >> >>     I have also had a disturbingly large amount of luck with >>     agent-assisted debugging. I have handed Claude the logs for >>     broken Kolla-Ansible deployed clusters, and it churns for a bit >>     and then tells me I have some subtle Neutron setting wrong. It >>     was also correct and saved me hours. I've been using a debug >>     bundle collection script in my private CI, but I have also had a >>     lot of success with giving the agent access to log aggregation >>     via loki or equivalent. That is, I think there are also useful >>     **operator** agent skills out there if we looked for them. >> >>     Would OpenStack accept a new project that delivers an "agent >>     skills" repository? > >     At the risk of starting a +1 pile on, I also feel a separate >     repository would make a lot of sense. Such a repo could/should >     have a large set of "cores" to help represent each project (note: >     they don't need to be existing cores: ops and other end users >     should be represented too). It would be very easy to refer to this >     from a per-project AGENTS.md and would avoid this information >     getting siloed in each project. I've also had success in >     hierarchial AGENTS.md placement: > >     ❯ tree ../ -L 1 > >     openstack > >     ├── agentsmd > >     ├── AGENTS.md > >     ├── aodh > >     ├── ... > >     └── zuul-jobs > > > > What do people think about me proposing my repository to the x > namespace then ? my main concern with that is that there are several diffent repos that diffent folks have that could act as a baseline so you coudl do that but so coudl i or any of the other pocs. tharther then selecting and blessing one as a base line i think it would be better to start form an empty repo and build it up with a group of intersted people

i started building https://github.com/SeanMooney/openstack-ai-style-guide in june with the hope fo evenraully "upstreaming it" to an opendev or openstack repo evrually in some form. i.e. import or select parts

https://github.com/sbauza/openstack-agentic-workflows/ does have many of the same element so we are derfintly not that divergent already which is nice but i think both repo have content that likely is not requried for a shared comuntiy repo. for example *jira-issue-triage* <https://github.com/sbauza/openstack-agentic-workflows/blob/main/workflows/jira-issue-triage> and

*gerrit-to-gitlab* <https://github.com/sbauza/openstack-agentic-workflows/blob/main/workflows/gerrit-to-gitlab> are

not relevent to upstram even if they could be for our downstream so should not be incldued my third party ci config/jobs is not relevent to the comunity either (although we could perhspa build a review job together eventually if there was interst in that)

Yeah of course, I wouldn't propose all my skills, just the ones that are for upstream.

while i hevially use subagents today https://github.com/SeanMooney/openstack-ai-style-guide/tree/master/agents

that is becuase i started this repo before skill exists and subagents are less portabel then skills. i used them because at the time the option was a subagent or a slash command and subagents had the benift of havign indepent context and the ablity to use diffent modeld per agent skill work in more tools, while they dont use seperate context that is actully ok in many cases.

there are also some layout decisions we would likely want to make such as prepare the repo as marketplace/plugin for tools that support that.

https://code.claude.com/docs/en/plugin-marketplaces https://docs.factory.ai/cli/configuration/plugins#claude-code-compatibility opencode are stilll discing this https://github.com/anomalyco/opencode/issues/7467

the agentskill comunity that run skills.md are also proposing standaristign a venfor nual location for this |.agents/skills|

https://github.com/agentskills/agentskills/issues/15 https://github.com/anomalyco/opencode/issues/10986

which is related to https://github.com/agentskills/agentskills/issues/27

this space is evolving and because of that i was advocating for not trying to have these in tree in every repo until clear portable standards emerge and are adopted

At the moment, for example look at my repo how we can use skills for both Cursor and Claude or other CLIs. We could change this once the agentskills community changes this (and then all the CLis use it)

it will be much similar for use to adapt these skills/agents/rules as the winner emerge if its in one repo.

i.e. openstack/ai-tools or whatever we settle on.

OK, based on those discussions, I proposed a patch to project-config https://review.opendev.org/c/openstack/project-config/+/984922 I don't want to bikeshed on the name but I'd want to avoid any term of AI, hence the naming I started to use. Once we agree on the direction, we could discuss about the skills by Gerrit comments, huzzah.

Nice to see a community starting up !

one thing to dicuss with the tc is shoudl this have its own project team or slot into an exsiting one like qa ectra and we need to see who are intersted in collaberating on this. basiclly all the normal new project stuff requried to be in the openstack namespce. perhaps we can bring that up in a future tc meeting proably after the ptg.

-Sylvain

>     Stephen > >> >>     Michael >

On 16/04/2026 14:06, Sylvain Bauza wrote:

Le jeu. 16 avr. 2026 à 14:51, Sean Mooney <smooney@redhat.com> a écrit :

On 16/04/2026 13:39, Sylvain Bauza wrote: > > > Le jeu. 16 avr. 2026 à 13:46, Sean Mooney <smooney@redhat.com> a écrit : > > > >     On 16/04/2026 10:34, Sylvain Bauza wrote: >     > >     > >     > Le jeu. 16 avr. 2026 à 11:04, Stephen Finucane >     <stephenfin@redhat.com> >     > a écrit : >     > >     >     On Thu, 2026-04-16 at 09:11 +1000, Michael Still wrote: >     >>     On Wed, Apr 15, 2026 at 11:30 PM Sylvain Bauza >     >>     <sbauza@redhat.com> wrote: >     >>> >     >>>     For sure, *skills* are for end-users and possibly >     different for >     >>>     each of us. >     >>>     *Knowledge data* and *personas (subagents)*, tho, can be >     shared >     >>>     between users and LLMs can use them upstream. >     >>> >     >> >     >>     I think there's an interesting point there which I don't >     think is >     >>     the point you're trying to make... >     >> >     >>     With Claude at least, skills can easily live outside of a >     >>     specific project repository. For example, there could be a git >     >>     repo of "recommended skills for OpenStack development" that >     >>     people check out to their ~/.claude/ **if they wanted to**, >     which >     >>     might improve the quality of their AI assisted work. That's >     also >     >>     likely to have fewer collisions than a single shared AGENTS.md >     >>     file, and also doesn't "pollute" the main repository with >     things >     >>     that some people clearly not ready to see. >     >> >     >>     The nice bit is, because they're just markdown files, the same >     >>     documentation is actually helpful to unassisted humans too. >     We're >     >>     talking effectively about a set of markdown files that state >     >>     things like: >     >> >     >>     * this is what a good release note looks like >     >>     * this is what a good sqlalchemy migration looks like >     >>     * this is how to write a new tempest test >     >>     * this is how _we_ write unit tests, which is definitely >     not the >     >>     default >     >>     * et cetera, et cetera >     >> >     >>     I have also had a disturbingly large amount of luck with >     >>     agent-assisted debugging. I have handed Claude the logs for >     >>     broken Kolla-Ansible deployed clusters, and it churns for a bit >     >>     and then tells me I have some subtle Neutron setting wrong. It >     >>     was also correct and saved me hours. I've been using a debug >     >>     bundle collection script in my private CI, but I have also >     had a >     >>     lot of success with giving the agent access to log aggregation >     >>     via loki or equivalent. That is, I think there are also useful >     >>     **operator** agent skills out there if we looked for them. >     >> >     >>     Would OpenStack accept a new project that delivers an "agent >     >>     skills" repository? >     > >     >     At the risk of starting a +1 pile on, I also feel a separate >     >     repository would make a lot of sense. Such a repo could/should >     >     have a large set of "cores" to help represent each project >     (note: >     >     they don't need to be existing cores: ops and other end users >     >     should be represented too). It would be very easy to refer >     to this >     >     from a per-project AGENTS.md and would avoid this information >     >     getting siloed in each project. I've also had success in >     >     hierarchial AGENTS.md placement: >     > >     >     ❯ tree ../ -L 1 >     > >     >     openstack >     > >     >     ├── agentsmd >     > >     >     ├── AGENTS.md >     > >     >     ├── aodh >     > >     >     ├── ... >     > >     >     └── zuul-jobs >     > >     > >     > >     > What do people think about me proposing my repository to the x >     > namespace then ? >     my main concern with that is that there are several diffent repos >     that >     diffent folks have that could act as a baseline so you coudl do >     that but >     so coudl i or any of the other pocs. >     tharther then selecting and blessing one as a base line i think it >     would >     be better to start form an empty repo and build it up with a group of >     intersted people > >     i started building > https://github.com/SeanMooney/openstack-ai-style-guide in june >     with the >     hope fo evenraully "upstreaming it" to an opendev or openstack repo >     evrually in some form. >     i.e. import or select parts > > https://github.com/sbauza/openstack-agentic-workflows/ does have >     many of >     the same element so we are derfintly not that divergent already >     which is >     nice >     but i think both repo have content that likely is not requried for a >     shared comuntiy repo. >     for example *jira-issue-triage* >     <https://github.com/sbauza/openstack-agentic-workflows/blob/main/workflows/jira-issue-triage> and > >     *gerrit-to-gitlab* >     <https://github.com/sbauza/openstack-agentic-workflows/blob/main/workflows/gerrit-to-gitlab> are > >     not relevent to upstram even if they could be for our downstream so >     should not be incldued >     my third party ci config/jobs is not relevent to the comunity either >     (although we could perhspa build a review job together eventually if >     there was interst in that) > > > Yeah of course, I wouldn't propose all my skills, just the ones that > are for upstream. > > >     while i hevially use subagents today > https://github.com/SeanMooney/openstack-ai-style-guide/tree/master/agents > >     that is becuase i started this repo before skill exists and >     subagents are less portabel then skills. >     i used them because at the time the option was a subagent or a slash >     command and subagents had the benift of havign indepent context >     and the >     ablity to use diffent modeld per agent >     skill work in more tools, while they dont use seperate context >     that is >     actully ok in many cases. > >     there are also some layout decisions we would likely want to make >     such >     as prepare the repo as marketplace/plugin for tools that support that. > > https://code.claude.com/docs/en/plugin-marketplaces > https://docs.factory.ai/cli/configuration/plugins#claude-code-compatibility >     opencode are stilll discing this > https://github.com/anomalyco/opencode/issues/7467 > >     the agentskill comunity that run skills.md are also proposing >     standaristign a venfor nual location for this |.agents/skills| > > https://github.com/agentskills/agentskills/issues/15 > https://github.com/anomalyco/opencode/issues/10986 > >     which is related to > https://github.com/agentskills/agentskills/issues/27 > >     this space is evolving and because of that i was advocating for not >     trying to have these in tree in every repo until >     clear portable standards emerge and are adopted > > > At the moment, for example look at my repo how we can use skills for > both Cursor and Claude or other CLIs. > We could change this once the agentskills community changes this (and > then all the CLis use it) > >     it will be much similar for use to adapt these skills/agents/rules as >     the winner emerge if its in one repo. > >     i.e. openstack/ai-tools or whatever we settle on. > > > OK, based on those discussions, I proposed a patch to project-config > https://review.opendev.org/c/openstack/project-config/+/984922 > I don't want to bikeshed on the name but I'd want to avoid any term of > AI, hence the naming I started to use. > Once we agree on the direction, we could discuss about the skills by > Gerrit comments, huzzah. > > Nice to see a community starting up ! one thing to dicuss with the tc is shoudl this have its own project team or slot into an exsiting one like qa ectra and we need to see who are intersted in collaberating on this. basiclly all the normal new project stuff requried to be in the openstack namespce.

perhaps we can bring that up in a future tc meeting proably after the ptg.

For now the proposal is to make it an unofficial project with its own community and maintainers but for sure we can discuss about having it shepherded by an existing official team or incepted officially as a separate team, but all those discussions should only happen once the agentic-workflows community agrees on making it ready to be an official project and then proposes it for adoption to the TC.

in that case it is not allwoed to be in the openstack namespace all project in the openstack nameapce must be a delvierbale of a project team and under the tc governace if i recall correctly. that does not mean it need to be anyting more the the |Emerging technology status | https://governance.openstack.org/tc/reference/emerging-technology-and-inacti... https://github.com/openstack/governance/blob/master/resolutions/20190322-nam... was intened to ensure that only offical tc project are listed uner the openstack namespace i can leave a coment in the gerrit patch and we can dicuss that mroe there.

-S

> > -Sylvain > > > >     >     Stephen >     > >     >> >     >>     Michael >     > >

Le jeu. 16 avr. 2026 à 16:04, Jeremy Stanley <fungi@yuggoth.org> a écrit :

On 2026-04-16 14:29:59 +0100 (+0100), Sean Mooney wrote: [...]

...

in that case it is not allwoed to be in the openstack namespace all project in the openstack nameapce must be a delvierbale of a project team and under the tc governace if i recall correctly. [...]

Or belong to a SIG, for example it might make sense to be part of the TaCT SIG if it's primarily for testing or collaboration uses.

I proposed to add this repo to the TaCT SIG here https://review.opendev.org/c/openstack/governance/+/984958 --

Jeremy Stanley

Le jeu. 16 avr. 2026 à 16:11, Jeremy Stanley <fungi@yuggoth.org> a écrit :

On 2026-04-16 11:34:21 +0200 (+0200), Sylvain Bauza wrote: [...]

...

What do people think about me proposing my repository to the x namespace then ? [...]

You can create any new Git namespace you like for this purpose, but don't reuse the existing x/ namespace. That was meant as a catch-all dumping ground for the projects whose maintainers didn't respond to OpenDev to let us know what namespace we should use for them back when unofficial projects were evicted from the openstack/ namespace in 2019. Any new repositories that don't fit into an existing descriptive namespace should pick a name for a new namespace.

At this point, we even have a linter check for project creation changes to prevent new additions to the x/ namespace so we don't accidentally approve any more.

Thanks Jeremy, that was something I had in mind afterwards, we discussed this on the Gerrit patch https://review.opendev.org/c/openstack/project-config/+/984922 Now this is proposed against the openstack namespace but we wonder which SIG to use for this repo but given your other email, I'll update the Gerrit patch to use the TaCT SIG for this repo. Thanks ! --

Jeremy Stanley

Le mar. 14 avr. 2026 à 20:53, Dan Smith <dms@danplanet.com> a écrit :

...

Philosophy: tell the agent to RTFM

+1000. If the M is missing stuff, we should fix the M and make the agents re-RT the F'ing M.

...

What each project adds

Like Sylvain said (I think), I really don't want the TC to legislate what projects need to do. I think coming up with a recommended guideline of being sparse and "Agents should RTFM" as a rule makes a lot of sense to me.

...

2. CLAUDE.md: a symlink to AGENTS.md. Not all tools support the same filename: most support AGENTS.md natively, but some (including Claude Code) look for CLAUDE.md instead. The symlink means both filenames resolve to the same content with nothing to keep in sync.

I commented on this in your proposal, but I would like to avoid doing this. I don't want to imply that people _should_ use Claude, or that we favor it over something else. I also don't want to give Claude any more reason to avoid reading the standard file. IMHO, if people are using Claude and they need to symlink, let them do it locally once per repo setup. We can git ignore it if it makes sense.

Agreed, we should only have AGENTS.md (see https://agents.md/ btw. for the format) and Claude Code should be able to look at this file instead of CLAUDE.md. Given of upstream, I agree with you, we should only have AGENTS.md and if people use Claude, they would just need to create a symlink by themselves.

...

3. ai/: a gitignored directory for agent session memory, plans, scratch notes, and ephemeral files. Agents are directed to prefer ai/tmp/ over the system temp directory so that all agent file I/O stays inside the repo tree, visible to the developer and sandboxed from shared system space. Only ai/.keep is committed.

I also commented on this but I see little reason to keep an empty directory in the git repo for this. It's a minor thing, of course, but most projects just git ignore things like build/ but don't actually commit the empty directory to the repo.

Agreed too, we could just add a specific directory in .gitignore if we need, but I don't see why we need this. For example, my own skills create a directory (called 'artifacts') but I don't want to add it upstream (so I just modify my own .gitignore personal file)

The scaffold is tool-agnostic. AGENTS.md [2] is the emerging

...

cross-tool standard, now stewarded by the Agentic AI Foundation under the Linux Foundation, with native support across Cursor, Codex, Aider, and others. Tools that do not support AGENTS.md typically support CLAUDE.md instead, which is why the symlink covers both cases with a single file to maintain. No tool names appear in the committed documentation; examples use generic placeholders. Any contributor, with any AI assistant, should get the same benefit.

Agree with all this, except that we should take it to the conclusion and not symlink for Claude :)

+1

...

1. Does this philosophy seem right: minimal scaffold, agents read the actual project docs? Or should projects invest in richer inline context files?

Minimal as you have suggested is my preference by far.

...

2. Is there value in the TC providing a cross-project baseline so projects do not each start from scratch? The openstack/hacking repository, which already owns shared coding standards, seems like a natural home for a baseline AGENTS.md that projects extend. Im Interested in views on that vs a new repo or just good old copy pasta

As above, I think guidelines and recommendations but not rules (or even an actual concrete baseline).

What we call 'rules' are LLM rules. For the moment, there is no abstract format for them but for example see https://cursor.com/en-US/docs/rules

...

3. Are there common gotchas shared across OpenStack projects (Gerrit workflow, DCO, stestr, pbr) that belong in such a baseline rather than being repeated per-repo?

Again, mentioned the the review, but I would want to avoid anything in the repo's agents config that gives an agent more permission (or perceived "agency") for doing thing like git commits. You may want to let yours do that, but I absolutely prohibit mine from doing things like git commit. So I just want to tread lightly on any instructions that may conflict with such a rule or imply that the agent could, if it wants, and follows the rules, ever commit to my repo.

That's what I wrote to Bogdan, I don't personally want to support *skills* into our upstream repository, just *knowledge usage* for LLMs. --Dan

On 4/15/26 15:39, Sylvain Bauza wrote:

Le mar. 14 avr. 2026 à 20:53, Dan Smith <dms@danplanet.com <mailto:dms@danplanet.com>> a écrit :

> Philosophy: tell the agent to RTFM

+1000. If the M is missing stuff, we should fix the M and make the agents re-RT the F'ing M.

> What each project adds

Like Sylvain said (I think), I really don't want the TC to legislate what projects need to do. I think coming up with a recommended guideline of being sparse and "Agents should RTFM" as a rule makes a lot of sense to me.

> 2. CLAUDE.md: a symlink to AGENTS.md. Not all tools support the same >    filename: most support AGENTS.md natively, but some (including >    Claude Code) look for CLAUDE.md instead. The symlink means both >    filenames resolve to the same content with nothing to keep in sync.

I commented on this in your proposal, but I would like to avoid doing this. I don't want to imply that people _should_ use Claude, or that we favor it over something else. I also don't want to give Claude any more reason to avoid reading the standard file. IMHO, if people are using Claude and they need to symlink, let them do it locally once per repo setup. We can git ignore it if it makes sense.

Agreed, we should only have AGENTS.md (see https://agents.md/ <https:// agents.md/> btw. for the format) and Claude Code should be able to look at this file instead of CLAUDE.md. Given of upstream, I agree with you, we should only have AGENTS.md and if people use Claude, they would just need to create a symlink by themselves.

> 3. ai/: a gitignored directory for agent session memory, plans, scratch >    notes, and ephemeral files. Agents are directed to prefer ai/tmp/ >    over the system temp directory so that all agent file I/O stays >    inside the repo tree, visible to the developer and sandboxed from >    shared system space. Only ai/.keep is committed.

I also commented on this but I see little reason to keep an empty directory in the git repo for this. It's a minor thing, of course, but most projects just git ignore things like build/ but don't actually commit the empty directory to the repo.

Agreed too, we could just add a specific directory in .gitignore if we need, but I don't see why we need this. For example, my own skills create a directory (called 'artifacts') but I don't want to add it upstream (so I just modify my own .gitignore personal file)

> The scaffold is tool-agnostic. AGENTS.md [2] is the emerging > cross-tool standard, now stewarded by the Agentic AI Foundation under > the Linux Foundation, with native support across Cursor, Codex, Aider, > and others. Tools that do not support AGENTS.md typically support > CLAUDE.md instead, which is why the symlink covers both cases with a > single file to maintain. No tool names appear in the committed > documentation; examples use generic placeholders. Any contributor, with > any AI assistant, should get the same benefit.

Agree with all this, except that we should take it to the conclusion and not symlink for Claude :)

+1

> 1. Does this philosophy seem right: minimal scaffold, agents read the >    actual project docs? Or should projects invest in richer inline >    context files?

Minimal as you have suggested is my preference by far.

> 2. Is there value in the TC providing a cross-project baseline so >    projects do not each start from scratch? The openstack/hacking >    repository, which already owns shared coding standards, seems like a >    natural home for a baseline AGENTS.md that projects extend. >    Im Interested in views on that vs a new repo or just good old >    copy pasta

As above, I think guidelines and recommendations but not rules (or even an actual concrete baseline).

What we call 'rules' are LLM rules. For the moment, there is no abstract format for them but for example see https://cursor.com/en-US/docs/rules <https://cursor.com/en-US/docs/rules>

> 3. Are there common gotchas shared across OpenStack projects (Gerrit >    workflow, DCO, stestr, pbr) that belong in such a baseline rather >    than being repeated per-repo?

Again, mentioned the the review, but I would want to avoid anything in the repo's agents config that gives an agent more permission (or perceived "agency") for doing thing like git commits. You may want to let yours do that, but I absolutely prohibit mine from doing things like git commit. So I just want to tread lightly on any instructions that may conflict with such a rule or imply that the agent could, if it wants, and follows the rules, ever commit to my repo.

That's what I wrote to Bogdan, I don't personally want to support *skills* into our upstream repository, just *knowledge usage* for LLMs.

Right, agents skills, personas (declarative identity), workflows (imperative procedures) are optional, and unlikely may or should be enforced in upstream projects. My intention with the linked agents repo prototype was exactly to teach ai agents about rules as advisory guidance, and how to do RTFM (external sources) efficiently.

--Dan

-- Best regards, Bogdan Dobrelya, Irc/Slack #bogdando

On Thu, Apr 16, 2026 at 10:48 PM Sylvain Bauza <sbauza@redhat.com> wrote:

(top-posting as we now have some consensus and a result)

A new project under the TaCT SIG was eventually incepted today (thanks fungi for accepting under the SIG umbrella again) : https://opendev.org/openstack/agentic-workflows I started to draft a series for a cross-projects skill support by https://review.opendev.org/q/status:open+project:openstack/agentic-workflows Contributors welcome, I feel alone on the agentic-workflows-core group, so free tickets to volunteers for reviews.

-S

I would like to express a concern. We started landing changes in this repository under the openstack namespace. One can think this repo now represents the OpenStack community's overall view on agentic development. But I feel such consensus hasn't formed yet. And some of such forming expected to happen next week on the PTG. Cheers, gibi

Le ven. 17 avr. 2026 à 15:12, Jeremy Stanley <fungi@yuggoth.org> a écrit :

On 2026-04-17 12:28:29 +0200 (+0200), Balazs Gibizer wrote: [...]

...

I would like to express a concern. We started landing changes in this repository under the openstack namespace. One can think this repo now represents the OpenStack community's overall view on agentic development. But I feel such consensus hasn't formed yet. And some of such forming expected to happen next week on the PTG.

I think it's fair to consider what's there as a placeholder, draft, proof-of-concept prototype, or similar starting point for group collaboration. It's a better use of PTG sessions to knock down a straw man proposal by discussing what you would change or keep, than to write it all from scratch in the limited time available.

Ideally people would start engaging on it sooner, volunteering to act as core reviewers for the repository, in preparation for related discussions next week.

Thanks Jeremy, that was the original intent, I just wanted to have a few files in the repo so people can understand the direction and tell whether they agree or not. We now have two new cores on this project btw. (Sean and Stephen F.) and we all agreed on waiting for the PTG discussions (on the TC slot) before merging any skill or other file (we don't have yet consensus about personas/subagents and rules but I leave that for the TC session) -Sylvain --

Jeremy Stanley