feat: add agent-ready skill (RHDH-aware, consolidated)

[johnmcollier]

Summary

• Adds agent-ready skill: runs the agentready CLI against a git repository, parses the assessment JSON, and walks through failing findings in tier order.
  • Auto mode — applies deterministic fixes immediately; prompts only when project-specific input is needed. Skips ADR/design intent findings to avoid fabricating rationale; notes them in the final summary.
  • Review mode — prompts yes/skip/defer/quit per finding; asks for human rationale before writing any ADR or design doc.
  • RHDH-aware — detects the repo from its git remote URL against rhdh-repos.md; uses matched context to pre-fill AGENTS.md sections and skip inapplicable findings. Degrades gracefully if the rhdh skill is not installed.
  • Batch mode — scans a local directory for RHDH repos and presents a score table; user picks any repo to drill into.
  • Inline AGENTS.md generation — no delegation; uses assessment data (detected languages, CI commands, repo context) to generate AGENTS.md and CLAUDE.md in one pass.
• Updates README with a new Repository Readiness section.

Test plan

• Run agent-ready on a repo with a low agentready score; verify findings are presented in tier order
• Verify agent_instructions finding generates AGENTS.md inline (not delegated)
• Verify RHDH repo detection works when remote URL matches rhdh-repos.md; gracefully skips if rhdh skill not installed
• Run in auto mode: confirm ADR/design findings are skipped, noted in summary
• Run in review mode: confirm each finding prompts; confirm ADR finding asks for rationale before writing
• Run batch mode: confirm only matched RHDH repos are assessed

[openshift-ci]

@johnmcollier: The label(s) /remove-label wip cannot be applied. These labels are supported: acknowledge-critical-fixes-only, platform/aws, platform/azure, platform/baremetal, platform/google, platform/libvirt, platform/openstack, ga, tide/merge-method-merge, tide/merge-method-rebase, tide/merge-method-squash, px-approved, docs-approved, qe-approved, ux-approved, no-qe, rebase/manual, cluster-config-api-changed, run-integration-tests, verified, ready-for-human-review, approved, backport-risk-assessed, bugzilla/valid-bug, cherry-pick-approved, jira/skip-dependent-bug-check, jira/valid-bug, ok-to-test, stability-fix-approved, staff-eng-approved. Is this label configured under labels -> additional_labels or labels -> restricted_labels in plugin.yaml?

Details

In response to this:

/remove-label wip

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.

[durandom]

Review: Skill Consolidation & Ecosystem Integration

1. Consolidate into a single agent-ready skill

init-agents-md is effectively "Step 4b" of agent-ready — it only runs when the agent_instructions finding fails. Keeping them separate means agent-ready delegates via Skill tool to init-agents-md, which has no context about the assessment that just ran. If they were one skill, the AGENTS.md generation could leverage the assessment findings directly (detected languages, existing CI config, test framework) instead of re-scanning everything from scratch.

Suggested: merge init-agents-md into agent-ready as a sub-step. One skill, one context, better results.

2. Leverage rhdh-repos.md for RHDH repositories

The rhdh core skill maintains a detailed reference of all 14 RHDH repos in references/rhdh-repos.md — tech stack, key paths, branching model, ecosystem relationships. When agent-ready runs against an RHDH repo, it could use this existing knowledge to:

• Pre-fill AGENTS.md sections instead of asking generic questions
• Skip findings that don't apply (e.g., lock file checks for a Bash-only repo)
• Suggest RHDH-specific conventions (branching model, release process)

Without this, the skill starts from zero on repos where we already have deep context.

3. Batch assessment across RHDH repos

The rhdh skill knows all repo paths via $RHDH config. A natural extension would be running agent-ready across all RHDH repos in one pass — e.g., "assess all our repos" or "which RHDH repos need AGENTS.md?". Currently there's no integration point for this.

4. skill-maker not used

The repo has a skill-maker skill specifically for creating new skills with interview, audit, and structural checklist. Using it would likely have caught the missing references/ directory and ensured consistency with existing skill patterns.

---

These are suggestions for making the skills feel native to this package rather than standalone tools. If the intent is to keep them fully generic (usable outside RHDH), that's valid — but then they might be a better fit as a separate plugin.

[johnmcollier]

Thanks for the thorough review @durandom — all four points are valid.

1. Consolidate into a single agent-ready skill
Agreed. The delegation to init-agents-md was the wrong call — AGENTS.md generation should be inline, using the assessment context (detected languages, existing CI, test framework) rather than re-scanning from scratch. Will fold it in this PR. init-agents-md stays as a standalone for independent use but agent-ready will no longer delegate to it.

2. Leverage rhdh-repos.md
Valid — these are RHDH skills and should feel native to the package. Will add RHDH repo detection and rhdh-repos.md context loading to pre-fill AGENTS.md sections and skip irrelevant findings.

3. Batch assessment across RHDH repos
Good idea. Will add it as an option when the skill is invoked without a path — "assess current directory or all RHDH repos?"

4. skill-maker not used
skill-maker was used — the skill structure, description optimization, and multiple audit passes all followed the skill-maker workflow during authoring. The absence of a references/ directory is intentional: per skill-maker guidance, simple linear skills under 500 lines keep all content inline and only split when domain knowledge outgrows the SKILL.md body. Happy to revisit if that intent isn't clear from the structure.

Will push an updated commit addressing 1–3.

[johnmcollier]

@durandom Oops, I forgot to commit/push the changes on Friday. Review should be addressed now

[durandom]

Re-review after consolidation refactor

The refactor cleanly addresses the three actionable points from the initial review — single skill, RHDH-aware detection, and batch mode. Nice work.

Two items to resolve before merging:

1. Missing version bump (blocker)

New skill requires a minor version bump to 0.4.0 per project conventions (AGENTS.md § Versioning). Four occurrences across three files:

• pyproject.toml
• .claude-plugin/plugin.json
• .claude-plugin/marketplace.json (2 occurrences)

2. Hardcoded rhdh-repos.md path

Step 2 references ~/.claude/skills/rhdh/references/rhdh-repos.md — this assumes a specific installation layout. If the rhdh skill is installed to a different prefix (e.g., via npx skills add), detection silently fails. The graceful degradation is fine, but the path assumption should be documented in the Gotchas section so future maintainers know why RHDH detection might not fire.

[durandom]

Heads up: PR #39 just merged and took the 0.4.0 version slot. When you add the version bump, please rebase on main and use 0.5.0.

[johnmcollier]

Thanks for the re-review @durandom.

Both items addressed in the latest commit:

1. Version bump — bumped to 0.5.0 (minor, per AGENTS.md conventions for new features) across pyproject.toml, plugin.json, and marketplace.json (2 occurrences).

2. rhdh-repos.md path assumption — added a note to the Gotchas section documenting the expected ~/.claude/skills/rhdh/references/rhdh-repos.md path and that silent degradation to generic mode is intentional if the path isn't found.

[johnmcollier]

@durandom Is this good to go in now?