docs: add AGENTS/CLAUDE — contributor orientation

[yazug]

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

[yazug]

Follow-on: README / AGENTS.md content distribution review

Now that both docs exist, a future pass should look at:

• Whether the Background / history section (Kolla → tripleo-tcib → tcib → S2I) belongs in README rather than AGENTS.md — README is more human-facing and the history is relevant to anyone reading the technical reference
• Whether any README technical detail would benefit from orienting context in AGENTS.md (e.g. the streams concept, the two-stage build model)

Not blocking for this draft — better done after initial contributor feedback clarifies where people get confused or find value in each doc.

[amoralej]

openstack_image_builder is still wip and the scope and final location is tbd. I wouldn't mention it yet.

[yazug]

ack, yea dropping that it crept in.

[amoralej]

The convention in openstack-k8s-operators project is to only include AGENTS.md. I think claude already checks at it.

[yazug]

ok cool, if that is the convention I am good with that and will trim this out.

[amoralej]

Thanks for adding it.

[amoralej]

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.

[yazug]

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.

[fmount]

yeah, on this point I think the path should be to focus more on README and docs/ to provide design decisions and other useful resources. We might want to keep AGENTS.md as simpler as possible and do not require to change it when something architectural is modified within the repo (e.g. directory structure or any other part that might impact the knowledge dumped here).

[amoralej]

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.

[yazug]

yea consistency is probably better to have across the documentation

[yazug]

Good pointes, I started digging around and found several suggestions for a better rubric for how to make it more concise and actionable

Rough initial rubric

The AGENTS.md Scoring Rubric

1. Conciseness & Token Budget (Max: 20 Points)

• 15–20 Points: Under 150 lines (ideally 30–60 lines for smaller repos). Contains zero redundant prose or generic instructions the model already knows.

• 8–14 Points: Between 150–300 lines. Some useful information, but includes boilerplate or explanations of standard project structures that the agent can deduce on its own.

• 0–7 Points: A massive wall of text or an unedited, auto-generated dump that wastes valuable context window space.

2. The Index-First Pattern (Max: 30 Points)

• 25–30 Points: Acts purely as a directory/map. Instead of duplicating architectural specs, it uses a clean Markdown table or reference list pointing directly to deep-dive files (e.g., docs/ARCHITECTURE.md, specific workflow guides).

• 15–24 Points: Contains some links, but mixes them with large blocks of explanatory text inline, making it harder for the agent to parse.

• 0–14 Points: Monolithic design. Tries to explain everything inline without pointing the agent to deeper documentation.

3. High-Value "Tribal Knowledge" & Invariants (Max: 30 Points)

• 25–30 Points: Documents non-obvious project-specific rules, silent failure modes, build quirks (especially relevant for S2I/OpenStack container build chains), and specific patterns that human reviewers constantly have to correct.

• 10–24 Points: Has general instructions like "write clean code" or standard linter commands, but misses project-specific gotchas.

• 0–9 Points: Completely devoid of custom heuristics; reads like a generic README.

4. Actionability of Commands & Workflows (Max: 20 Points)

• 15–20 Points: Provides exact, copy-pasteable commands for building, testing, or running container/S2I checks specific to the repository's Makefile or CI scripts.

• 8–14 Points: Lists commands, but they are out-of-date or lack necessary environment context.

• 0–7 Points: Omits operational commands entirely.

Quick Self-Test / Litmus Test

For every single line you wrote in your PR #22 file, ask yourself this question:

"Would removing this line cause an AI coding agent to make a mistake it wouldn't otherwise make?"

If the answer is no, cut it. Focus your AGENTS.md strictly on pointing the agent to the right deep-dive docs and highlighting the hidden traps unique to building OpenStack S2I container images.

---

the initial draft of this scored a 49/100 with a lot of fluff and not a lot of actionable content.