chore(agent-readiness): bootstrap basic AGENTS.md and minor repo updates

[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

🐞 Bugs (2) 📘 Rule violations (0) 📜 Skill insights (0)

1. Shellcheck misses subdir scripts 🐞 Bug ⚙ Maintainability

Description

The new lint instructions only run shellcheck *.sh, which lints root-level scripts only and skips
tracked scripts in subdirectories (e.g. scripts/sync-lightspeed-configs.sh). This reduces lint
coverage and can let shell issues ship unnoticed despite make lint/docs implying shell scripts
were checked.

Code

Makefile[R22-24]

+lint:
+	npx dclint .
+	shellcheck *.sh

Relevance

⭐⭐⭐ High

Team previously accepted feedback that *.sh patterns are too broad/incorrect for subdirs; prefers
correct scoping.

PR-#121
PR-#58

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The Makefile and agent docs lint only *.sh in the repo root, but the repo contains shell scripts
under scripts/ that will not match that glob when invoked from the root directory.

Makefile[22-24]
AGENTS.md[12-16]
scripts/sync-lightspeed-configs.sh[1-5]

Agent prompt

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

## Issue description
`make lint` currently runs `shellcheck *.sh`, which only matches shell scripts in the repo root and misses scripts under subdirectories.

## Issue Context
There is at least one shell script under `scripts/` that is skipped by the current glob.

## Fix Focus Areas
- Makefile[22-24]
- AGENTS.md[12-16]

## Suggested fix
- Replace `shellcheck *.sh` with a command that targets all tracked `.sh` files, e.g.:
 - `shellcheck $(shell git ls-files '*.sh')`
 - or `find . -name '*.sh' -type f -print0 | xargs -0 shellcheck`
- Update `AGENTS.md` to mirror the corrected command so agents/users run the same complete lint.

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

---

2. Hook lints all YAML files 🐞 Bug ⚙ Maintainability

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.

Code

.claude/settings.json[9]

+            "command": "FILE=\"$CLAUDE_FILE_PATH\"; case \"$FILE\" in *.yaml|*.yml) npx --yes dclint \"$FILE\" 2>/dev/null || true ;; *.sh) shellcheck \"$FILE\" 2>/dev/null || true ;; esac"

Relevance

⭐⭐ Medium

No prior reviews about scoping dclint to compose-only YAML; existing CI runs npx dclint . broadly.

PR-#32
PR-#180

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The hook’s case statement matches any YAML filename, and the repo includes YAML files that are not
Docker/Podman Compose manifests.

.claude/settings.json[5-10]
mkdocs.yaml[1-7]
catalog-info.yaml[1-5]

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

---

[johnmcollier]

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