[ENHANCEMENT] realign and restructure AGENTS file with current codebase

[filip-komarzyniec]

Enhancement Type

• Enhancement to existing component/pipeline
• Repository tooling/automation improvement
• CI/CD enhancement
• Documentation improvement
• Testing framework improvement
• Other repository enhancement (please specify) (AGENTS.md file)

Component/Pipeline Information

Name:

Category:

Problem Statement

Running an agent on the current AGENTs.md file it seems there are some inconsistencies and places for possible improvements with regard to the current codebase state. It would be beneficial to revisit the file and align it with the current code.

Proposed Solution

The following is proposed by Claude:

1. Container/OCI image guidance is entirely missing. The repo uses Containerfile (not Dockerfile), publishes to ghcr.io/kubeflow/pipelines-components-<name>, and enforces allowed base image prefixes (ghcr.io/kubeflow/, python:<version>). An agent authoring a component with a custom image would have no guidance from AGENTS.md.

2. Import guard rule is underspecified. The validations table mentions it but doesn't state the actual constraint: top-level imports must be stdlib only. This is non-obvious and an agent would violate it without knowing the rule.

3. Conventional Commits not mentioned. CONTRIBUTING.md requires them. An agent creating commits would produce free-form messages without this.

4. Branching model absent. main + release-<major>.<minor> with z-stream patches — relevant for agents deciding which branch to target.

5. Prerequisites not listed. Python 3.11+, uv, pre-commit, Docker/Podman, kubectl — useful for Mode 3 agents or any agent needing to validate its environment.

6. lastVerified SLA is vague. AGENTS.md says "keep lastVerified fresh" but the actual policy is: 12-month maximum, warning at ~9 months, removal at 12 months. Concrete numbers matter for an agent deciding whether to update it.

7. Deprecation/lifecycle process missing. GOVERNANCE.md defines a two-release deprecation window with specific steps (mark in metadata/README, provide migration guidance, then remove). Not covered at all.

8. scripts/lib/ shared library not called out for Mode 3. Agents maintaining scripts should know about the reusable modules (discovery.py, parsing.py, base_image.py, kfp_compilation.py).

9. Several CI workflows missing from the validations table. compile-and-deps.yml, container-build-matrix-check.yml, container-build.yml, build-packages.yml, package-entries-check.yml aren't referenced.

10. Test discovery nuance. pyproject.toml sets testpaths = ["scripts"] and excludes components//pipelines/ via norecursedirs — so component/pipeline tests require explicit paths on the pytest CLI. An agent running tests without this knowledge would miss them.

11. PROW/OWNERS mechanics could be more explicit. The review flow mentions /lgtm + /approve in passing but doesn't explain that this repo uses Kubernetes-style OWNERS files (not GitHub CODEOWNERS) with PROW automation.

Use Cases

1. Co-contributing to the codebase with Claude or different agent
2. Automating different workflows around the repository using agents

Alternatives Considered

Willing to Contribute

• Yes, I can implement this enhancement
• Yes, I can help with testing
• Yes, I can help with documentation
• No, requesting community implementation

---

Interested in this enhancement? Give it a 👍.