[johnmcollier]

Description

Ran the agent-ready (https://github.com/redhat-developer/rhdh-skill/blob/main/skills/agent-ready/SKILL.md) skill against the repository, to address some gaps called out by the https://github.com/ambient-code/agentready CLI (to assess an individual repository's readiness to be consumed by agents).

• Adds an AGENTS.md / CLAUDE.md with basic one-line build and test commands, and a link to some repo docs that could be found
  • To the maintainers: I recommend populating the Key convention and Architecture sections for stuff that isn't immediately obvious to an agent
    • Do not auto generate this information, as it can actively harm agent effectiveness
• A couple minor updates to the repo and a claude hook to improve agent consumption

Which issue(s) does this PR fix or relate to

N/A, but see https://docs.google.com/spreadsheets/d/1Gk3nDQFJ2PBaaPiMZ3naJqAWf-nmL14OwK-Y83k7cuc/edit for more information

PR acceptance criteria

• Tests
• Documentation

How to test changes / Special notes to the reviewer

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[rhdh-qodo-merge]

PR Summary by Qodo

Bootstrap agent-ready docs, Claude hooks, and a convenience Makefile
📝 Documentation ⚙️ Configuration changes 🕐 10-20 Minutes

Description

• Add AGENTS.md/CLAUDE.md with clear start/stop/lint commands for agent workflows
• Introduce Claude PostToolUse hooks to auto-lint edited YAML and shell scripts
• Add a Makefile to standardize common local compose and lint operations

Diagram

graph TD
  A["Agent/Claude"] --> B["CLAUDE.md"] --> C["AGENTS.md"]
  A --> D["Makefile targets"]
  A --> E[".claude/settings.json"] --> F["Linters (dclint/shellcheck)"] --> G["Touched *.yml/*.sh"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Adopt pre-commit (or lefthook) for local lint automation

• ➕ Works for all contributors, not only Claude sessions
• ➕ Centralized, predictable execution on commit
• ➖ More setup/maintenance overhead (tooling install + hook management)
• ➖ Can slow down contributor workflow if not tuned

2. Keep a single agent guide in README.md instead of AGENTS.md/CLAUDE.md

• ➕ Fewer files; less duplication risk
• ➕ More visible to humans by default
• ➖ Agent-specific instructions can get diluted among general documentation
• ➖ Less compatible with agent-ready conventions expecting AGENTS.md/CLAUDE.md

Recommendation: The PR’s light-touch approach (AGENTS.md + CLAUDE.md pointer + Claude-only lint hooks + Makefile) is a good baseline because it improves agent usability without imposing new tooling on all contributors. If the team wants consistent linting beyond agent sessions, consider adding pre-commit later as an opt-in/CI-aligned follow-up.

Files changed (4) +88 / -0

Documentation (2) +49 / -0

AGENTS.mdAdd agent-facing repo guide with build/test and lint commands +48/-0

Add agent-facing repo guide with build/test and lint commands

• Creates an AGENTS.md playbook for running RHDH Local via podman/docker compose, reinstalling dynamic plugins, and linting compose/shell files. Includes maintainer TODO sections for non-obvious conventions and architecture notes plus pointers to canonical repo examples.

AGENTS.md

CLAUDE.mdPoint CLAUDE.md to AGENTS.md +1/-0

Point CLAUDE.md to AGENTS.md

• Adds a minimal CLAUDE.md that delegates all guidance to AGENTS.md to keep a single source of truth.

CLAUDE.md

Other (2) +39 / -0

settings.jsonAdd Claude PostToolUse hooks to lint edited YAML and shell scripts +15/-0

Add Claude PostToolUse hooks to lint edited YAML and shell scripts

• Introduces a Claude hook that runs dclint on *.yml/*.yaml and shellcheck on *.sh after Edit/Write operations. The commands are best-effort (errors suppressed) to keep agent workflows unblocked.

.claude/settings.json

MakefileAdd Makefile targets for compose lifecycle, plugin install, and linting +24/-0

Add Makefile targets for compose lifecycle, plugin install, and linting

• Introduces standard targets (start/stop/restart/clean/plugins-install/lint) with a TOOL switch (podman default, docker supported). Provides a repeatable interface for agents and humans to run common local operations.

Makefile

[rhdh-qodo-merge]

Code Review by Qodo

View medium (2)

1. Claude hook is shipped even though it does nothing 🐞 Bug ⭐ New

Description

The PostToolUse command in .claude/settings.json reads $CLAUDE_FILE_PATH, which Claude Code does
not export, so FILE is empty and the case matches nothing, while the PR's stated goal (commit 4)
is to remove this hook yet the net diff still adds it. The hook also runs npx --yes dclint on
every edited YAML file, fetching and executing an unpinned npm package and hiding all failures with
2>/dev/null || true, which conflicts with the PR's pinned-container, no-npx lint policy and lets a
changed upstream package run on any developer machine that edits YAML.

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PR adds `.claude/settings.json` with a PostToolUse hook that has two problems. Its command reads `$CLAUDE_FILE_PATH`, which Claude Code does not export, so the hook is a no-op even though the commit history says the hook was meant to be removed. The same command runs `npx --yes dclint` on every edited YAML file, which fetches and executes an unpinned npm package and silences all errors with `2>/dev/null || true`. This conflicts with the project's pinned-container, no-npx lint policy and the Makefile's pinned `DCLINT_IMAGE`.

## Fix Focus Areas
- .claude/settings.json[1-15]
- .claude/settings.json[9-9]
- Makefile[30-34]

## Recommended Fix
Delete `.claude/settings.json` from this PR, as the commit history intends. If a hook is still wanted, do not use `npx`. Have it call the pinned `make lint` target or the pinned `zavoloklom/dclint:3.1.0` container image, base it on a variable Claude Code actually exports, and remove `2>/dev/null || true` so failures are visible. Verify it fires on an Edit before merging.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

2. AGENTS.md branching rule contradicts accepted ADR 🔗 Cross-repo conflict ⭐ New

Description

The new AGENTS.md branching bullet tells contributors to target dev for docs and dependency
updates and says never to target main. The accepted rhdh-adr 007 ADR says version-independent
changes such as documentation and GitHub Actions dependency updates may target main directly, and
reserves dev for RHDH-version-specific work.

Dismiss ↗ | View ↗

View low (1)

3. Hook lints all YAML files 🐞 Bug

Description

The Claude PostToolUse hook runs dclint for any edited *.yaml/*.yml file, including
non-Compose YAML like mkdocs.yaml and catalog-info.yaml. This broad matcher lowers the signal of
the hook because it applies a Compose-focused linter beyond Compose files.

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The `.claude/settings.json` hook runs `dclint` on every YAML file edit, even when the YAML is not a Compose file.

## Issue Context
The repository contains multiple non-Compose YAML files (TechDocs/mkdocs config, Backstage catalog entities, dynamic plugin configs).

## Fix Focus Areas
- .claude/settings.json[5-10]

## Suggested fix
- Narrow the `case` pattern to only match Compose files/overlays, for example:
 - `*compose*.yaml|*compose*.yml)`
 - or a more explicit allowlist like `compose.yaml|compose-*.yaml|compose.*.yaml|compose-*.yml)`
- Keep the `.sh` handling as-is.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

[johnmcollier]

Hey @rm3l @kadel mind reviewing this PR when you get the chance?

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[rm3l]

Thanks @johnmcollier , and sorry for the delay reviewing this. I've filled in some of the key conventions and architecture details in the AGENTS.md file, and also quickly expanded the Makefile to include additional useful targets.

[rm3l]

/cherrypick main

[openshift-cherrypick-robot]

@rm3l: new pull request created: #417

Details

In response to this:

/cherrypick main

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.