diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index fae8fcf..3d1f67c 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -5,14 +5,14 @@ }, "metadata": { "description": "Orchestrator skill for RHDH plugin development - onboard, update, and maintain plugins in the Extensions Catalog", - "version": "0.4.0" + "version": "0.5.0" }, "plugins": [ { "name": "rhdh", "source": "./", "description": "Skills for RHDH plugin lifecycle management", - "version": "0.4.0", + "version": "0.5.0", "strict": true } ] diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 342541c..758136d 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "rhdh", "description": "All-in-one toolkit for Red Hat Developer Hub (RHDH). Covers plugin development, overlay management, environment setup, version compatibility, CI/CD, and RHDH ecosystem navigation.", - "version": "0.4.0", + "version": "0.5.0", "author": { "name": "RHDH Store Manager" }, diff --git a/README.md b/README.md index edbd8c0..940b349 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,10 @@ Track work across the four RHDH Jira projects. - **[rhdh](./skills/rhdh/SKILL.md)** — Entry point and router. Detects your environment, runs `doctor` checks, maintains a cross-session worklog, and routes to the right skill. Start here if you're not sure what you need. +### Repository Readiness + +- **[agent-ready](./skills/agent-ready/SKILL.md)** — Assess RHDH repositories against agentready criteria and address each gap. RHDH-aware: detects the repo from its remote URL, uses `rhdh-repos.md` context to pre-fill `AGENTS.md` and skip inapplicable findings. Supports single-repo and batch modes (assess all RHDH repos in one pass). + ### Meta - **[skill-maker](./skills/skill-maker/SKILL.md)** — Create new skills or consolidate existing ones following the [Agent Skills open standard](https://agentskills.io/specification). Interviews you about scope and edge cases before drafting. diff --git a/pyproject.toml b/pyproject.toml index e6f9153..bad9a86 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "rhdh-skill" -version = "0.4.0" +version = "0.5.0" description = "Claude Code skill for RHDH plugin development" readme = "README.md" license = "Apache-2.0" diff --git a/skills/agent-ready/SKILL.md b/skills/agent-ready/SKILL.md new file mode 100644 index 0000000..a0bcf67 --- /dev/null +++ b/skills/agent-ready/SKILL.md @@ -0,0 +1,225 @@ +--- +name: agent-ready +description: | + Assesses a git repository's readiness for use by AI coding agents using the agentready CLI, then walks through and addresses each gap. RHDH-aware: detects RHDH repositories and uses rhdh-repos.md context to pre-fill AGENTS.md and skip inapplicable findings. Use when asked to "assess agent readiness", "run agentready", "check how agent-ready this repo is", "make this repo agent-ready", "improve agent readiness score", "assess all RHDH repos", "batch agent readiness", or "onboard this repo for agents". +--- + +## Prerequisites + +`uvx` is a hard dependency. Verify it is available before any other step: + +```bash +uvx --version +``` + +If missing, stop: "`uvx` is required. Install via `pip install uv` or see [uv installation](https://docs.astral.sh/uv/getting-started/installation/)." + +## Step 1: Mode selection + +If no path was provided, present a structured choice: + +- **Single repo** — assess the current working directory (default) +- **Batch** — assess all RHDH repositories (see Batch mode below) + +If a path was provided, skip this and proceed to Step 2. + +## Step 2: Setup + +**Path:** Use the provided path, or `.` for the current directory. Validate it is a git repository: + +```bash +git -C . rev-parse --is-inside-work-tree # replace . with path if provided +``` + +If not a git repository, stop and tell the user. + +**RHDH detection:** Check the repo's git remote URL: + +```bash +git -C remote get-url origin 2>/dev/null +``` + +Attempt to read `~/.claude/skills/rhdh/references/rhdh-repos.md`. If the file does not exist, skip RHDH detection and proceed with generic assessment — do not stop or warn the user. If found, check whether the remote URL matches any repo's upstream URL. If matched, note the repo name, tech stack, key paths, and conventions — these inform AGENTS.md generation and finding triage. Store as `rhdh_context`. + +**Config file:** Only use a config file if the user explicitly provided one. Do not ask. + +## Step 3: Run the assessment + +```bash +REPORT_DIR=$(mktemp -d) # on Windows: use %TEMP% or Python tempfile +uvx --from git+https://github.com/ambient-code/agentready agentready -- assess \ + -o "$REPORT_DIR" \ + +``` + +Append `-c ` if the user provided a config file. + +Note the value of `$REPORT_DIR` — shell variables do not persist across tool calls. + +Parse `$REPORT_DIR/assessment-latest.json`. Extract: +- `overall_score`, `certification_level` +- `findings` — each with `attribute.id`, `attribute.tier`, `attribute.default_weight`, `attribute.name`, `status`, `score`, `evidence`, `remediation` + +## Step 4: Present summary + +``` +Score: /100 — +Failing: findings ( Tier 1, Tier 2, ...) +``` + +If no failing findings, congratulate the user and stop. + +Otherwise ask: + +> "Fix applicable findings automatically, or review each one individually? +> **auto** (default) — apply self-contained fixes immediately; prompt only when input is needed +> **review** — prompt yes/skip/defer/quit for every finding" + +Default to **auto** if the user says yes, presses Enter, or says "fix everything". + +## Step 5: Work through findings + +Work only through `status == "fail"` findings. Skip `not_applicable` and `pass` silently. + +**Sort order:** ascending tier, then descending `attribute.default_weight` within each tier. + +If `rhdh_context` is set, skip findings that clearly don't apply to the detected tech stack (e.g., lock file checks for a Bash-only repo, `src/` layout for a GitOps YAML repo) — note them in the summary. + +### Auto mode + +Apply each fix without prompting **unless**: + +- The fix requires project-specific input (CI platform, package ecosystem) +- The finding might not apply to this repo type — present it and ask whether to apply or skip + +**Skip without prompting:** ADRs, design intent, architecture decisions — these require human rationale. Note them in the final summary. + +For the `agent_instructions` finding, follow the inline AGENTS.md generation in the `agent_instructions` section below — this applies in both auto and review modes. + +After processing, list what was applied, prompted, and skipped, then proceed to Step 6. + +### Review mode + +For each finding: + +``` +[Tier ] — /100 +Evidence: + +Remediation: + +Apply this fix? [yes / skip / defer / quit] +``` + +**yes** — apply the fix, then move to the next finding. +**skip** — move on; do not revisit. Use this if the finding doesn't apply to this repo. +**defer** — note it; surface again after re-run. +**quit** — stop immediately. + +**ADR and design intent findings:** Do not use JSON remediation. Ask instead: + +> "Do you have any architectural decisions worth capturing? Describe the decision and rationale — I'll write the ADR. Skip to add manually later." + +Write only if the user provides input. Never invent rationale. + +### `agent_instructions` finding (both modes) + +Generate `AGENTS.md` and `CLAUDE.md` inline — do not delegate to another skill. + +**Scan the repo for commands:** +- `package.json` → `scripts` entries (build, test, lint, typecheck, dev) +- `Makefile` / `GNUmakefile` → targets +- `pyproject.toml` → `[tool.pytest]`, `[tool.ruff]`, `[tool.mypy]`, `[project.scripts]` +- `.github/workflows/*.yml` → `run:` steps containing test/lint/build/typecheck keywords + +**If `rhdh_context` is set:** pull key paths, tech stack, conventions, and branching model directly from the matched `rhdh-repos.md` entry — use these to pre-fill AGENTS.md sections and skip generic questions where RHDH context already answers them. + +**If not RHDH (or RHDH context doesn't cover it):** ask these three questions one at a time: +1. "What are 2-3 conventions an agent couldn't discover by reading the code? Skip if none." +2. "Any non-obvious architectural decisions or places where things live unexpectedly? Skip if obvious." +3. "Any commit format, CI checks, or PR conventions agents should know? Skip if standard." + +Write `AGENTS.md`: + +```markdown +# + +## Build & Test Commands +- Build: `` +- Test all: `` +- Test single file: `` +- Lint: `` +- Type check: `` + +## Key Conventions + + +## Architecture + + +## PR Conventions +- Agent-assisted commits should include an `Assisted-by: ` footer + +``` + +Write `CLAUDE.md` with exactly: `@AGENTS.md` + +Omit any section — including its header — where there is nothing to say. Do not invent content. + +### Applying other fixes (both modes) + +Use `remediation.steps`, `remediation.commands`, and `remediation.examples` from the JSON. Do not invent steps beyond what the JSON provides. + +## Step 6: Re-run and present results + +```bash +REPORT_DIR=$(mktemp -d) # on Windows: use %TEMP% or Python tempfile +uvx --from git+https://github.com/ambient-code/agentready agentready -- assess \ + -o "$REPORT_DIR" \ + +``` + +Show before/after: + +``` +Before: /100 () +After: /100 () + +Remaining failures: findings +``` + +If remaining failures (including deferred), ask: "Would you like to continue addressing the remaining findings?" If yes, repeat Step 5. + +## Batch mode + +When the user selects batch assessment: + +1. Ask: "What directory are your RHDH repos cloned into? (e.g. `~/git`)" +2. Find subdirectories that are git repos: + +```bash +find -maxdepth 2 -name ".git" -type d | sed 's|/.git||' +``` + +3. For each, check if the remote URL matches a repo in `rhdh-repos.md`. Assess only matching repos. +4. Run the assessment on each matched repo (Step 3) and collect results. +5. Present a summary table: + +``` +Repo Score Level Failing +rhdh 72/100 Bronze 4 +rhdh-operator 45/100 Needs Improvement 11 +rhdh-plugins 88/100 Silver 1 +``` + +6. Ask: "Would you like to address findings for any of these repos?" If yes, the user picks one — run Step 3 (assessment) on that repo to get fresh findings, then run Steps 4–6 for it. + +## Gotchas + +- The first `uvx` run fetches and builds agentready from GitHub — this can take 30–60 seconds. Subsequent runs use the cache. If the fetch fails, stop — do not proceed without a valid report. +- Do not output the report to the repository directory — use the temp dir to avoid polluting the working tree. +- `not_applicable` findings reflect the detected language stack; do not mention them unless the user asks. +- Deferred findings surface again after the re-run. +- Never invent rationale for ADRs or design docs. In auto mode, skip them. In review mode, ask for rationale before writing anything. +- In batch mode, only assess repos whose remote URL matches `rhdh-repos.md` — do not assess unrelated repos in the same directory. +- `rhdh-repos.md` is expected at `~/.claude/skills/rhdh/references/rhdh-repos.md` — the default install path when using `npx skills add redhat-developer/rhdh-skill`. If the `rhdh` skill was installed to a different prefix, RHDH detection will silently degrade to generic mode. This is by design — no error, no warning.