docs: add AGENTS/CLAUDE — contributor orientation - #22
Conversation
Adds agent-bootstrappable orientation for both human contributors and AI agents loading this repo as context. Covers the S2I build model, repo structure, RPM source rules, CI, and common anti-patterns. Register is intentionally hybrid (prose for orientation, directive for rules). A follow-on pass to tighten Anti-Patterns and RPM Source Rules sections to imperative register would sharpen it. CI Tooling Conventions section is a placeholder stub — a natural home for CI/tooling code constraints as that work stabilizes. Interesting experiment from day-of-learning efforts Assisted-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Jon Schlueter <jschluet@redhat.com>
Per working group feedback: skill links belong in README so agents discover them through project docs rather than fetching URLs directly from AGENTS.md. Also adds README pointer at top of AGENTS.md as the authoritative technical reference. Assisted-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
|
Follow-on: README / AGENTS.md content distribution review Now that both docs exist, a future pass should look at:
Not blocking for this draft — better done after initial contributor feedback clarifies where people get confused or find value in each doc. |
…ridge) Use <image> consistently to match README. Note that component group == project in README terminology; component framing comes from earlier tooling (DLRN). Assisted-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Standardize on 'pull request' throughout (was mixed PR/pull request). Wrap bare containers/base/rpms.repo path references in link syntax. Remaining skillsaw finding (actionability score 20/100) is expected for an orientation doc — different target than a directive/runbook. Assisted-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
openstack_image_builder is from Sean's [DNM] prototype (PR openstack-k8s-operators#14) and not yet merged or widely known. Replaced with plain language; skill reference and 'see open pull requests' are enough. Assisted-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
| each individual container, and populate it with the files described in | ||
| [Repo Structure](#repo-structure). Use an existing container as your template. | ||
|
|
||
| **Tooling:** `openstack_image_builder` (OIB) is being developed to assist with image |
There was a problem hiding this comment.
openstack_image_builder is still wip and the scope and final location is tbd. I wouldn't mention it yet.
There was a problem hiding this comment.
ack, yea dropping that it crept in.
| @@ -0,0 +1 @@ | |||
| See [AGENTS.md](AGENTS.md) for project context and contributor guidance. | |||
There was a problem hiding this comment.
The convention in openstack-k8s-operators project is to only include AGENTS.md. I think claude already checks at it.
There was a problem hiding this comment.
ok cool, if that is the convention I am good with that and will trim this out.
|
|
||
| ## Tooling | ||
|
|
||
| The `/generate-containerfiles` Claude Code skill is available in the |
| > is actively being worked out. See the open pull requests for current work in this area. | ||
| > Details will be added here as they stabilize. | ||
|
|
||
| ## Repo Structure |
There was a problem hiding this comment.
In general, my doubt about this section is how much of this should be here and how much should be in README.md. I'm in favor in improving README.md and potentially other docs files and making AGENTS.md as lean as possible.
@fmount has been actively adding AGENTS.md in other repos so he probably has a better criteria.
There was a problem hiding this comment.
yea that is something I was struggling with and I forgot to check what was actually in the README to start with. but some refinement is probably in order.
| ``` | ||
| containers/ | ||
| base/ # shared base image — inherited by all service images | ||
| <component-group>/ # one directory per upstream service group (called "project" in README) |
There was a problem hiding this comment.
I'd try to keep consistent to terms accross docs. Although it explicitely mentions that README calls it project, i'd try to keep it simple and use consistent terminology. I used project because i think the natural criteria for that level is per openstack project because all the images on it will install the same service project although more elaborated organizations may be done.
There was a problem hiding this comment.
yea consistency is probably better to have across the documentation
2 participants
Adds agent-bootstrappable orientation for both human contributors and AI
agents loading this repo as context. Covers the S2I build model, repo
structure, RPM source rules, CI, and common anti-patterns.
Register is intentionally hybrid (prose for orientation, directive for
rules). A follow-on pass to tighten Anti-Patterns and RPM Source Rules
sections to imperative register would sharpen it.
CI Tooling Conventions section is a placeholder stub — a natural home
for CI/tooling code constraints as that work stabilizes.
Interesting experiment from day-of-learning efforts
Assisted-by: Claude Sonnet 4.6 (1M context) noreply@anthropic.com
Signed-off-by: Jon Schlueter jschluet@redhat.com