|
| 1 | +--- |
| 2 | +name: agent-ready |
| 3 | +description: | |
| 4 | + 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". |
| 5 | +--- |
| 6 | + |
| 7 | +## Prerequisites |
| 8 | + |
| 9 | +`uvx` is a hard dependency. Verify it is available before any other step: |
| 10 | + |
| 11 | +```bash |
| 12 | +uvx --version |
| 13 | +``` |
| 14 | + |
| 15 | +If missing, stop: "`uvx` is required. Install via `pip install uv` or see [uv installation](https://docs.astral.sh/uv/getting-started/installation/)." |
| 16 | + |
| 17 | +## Step 1: Mode selection |
| 18 | + |
| 19 | +If no path was provided, present a structured choice: |
| 20 | + |
| 21 | +- **Single repo** — assess the current working directory (default) |
| 22 | +- **Batch** — assess all RHDH repositories (see Batch mode below) |
| 23 | + |
| 24 | +If a path was provided, skip this and proceed to Step 2. |
| 25 | + |
| 26 | +## Step 2: Setup |
| 27 | + |
| 28 | +**Path:** Use the provided path, or `.` for the current directory. Validate it is a git repository: |
| 29 | + |
| 30 | +```bash |
| 31 | +git -C . rev-parse --is-inside-work-tree # replace . with path if provided |
| 32 | +``` |
| 33 | + |
| 34 | +If not a git repository, stop and tell the user. |
| 35 | + |
| 36 | +**RHDH detection:** Check the repo's git remote URL: |
| 37 | + |
| 38 | +```bash |
| 39 | +git -C <path> remote get-url origin 2>/dev/null |
| 40 | +``` |
| 41 | + |
| 42 | +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`. |
| 43 | + |
| 44 | +**Config file:** Only use a config file if the user explicitly provided one. Do not ask. |
| 45 | + |
| 46 | +## Step 3: Run the assessment |
| 47 | + |
| 48 | +```bash |
| 49 | +REPORT_DIR=$(mktemp -d) # on Windows: use %TEMP% or Python tempfile |
| 50 | +uvx --from git+https://github.com/ambient-code/agentready agentready -- assess \ |
| 51 | + -o "$REPORT_DIR" \ |
| 52 | + <path> |
| 53 | +``` |
| 54 | + |
| 55 | +Append `-c <config-path>` if the user provided a config file. |
| 56 | + |
| 57 | +Note the value of `$REPORT_DIR` — shell variables do not persist across tool calls. |
| 58 | + |
| 59 | +Parse `$REPORT_DIR/assessment-latest.json`. Extract: |
| 60 | +- `overall_score`, `certification_level` |
| 61 | +- `findings` — each with `attribute.id`, `attribute.tier`, `attribute.default_weight`, `attribute.name`, `status`, `score`, `evidence`, `remediation` |
| 62 | + |
| 63 | +## Step 4: Present summary |
| 64 | + |
| 65 | +``` |
| 66 | +Score: <overall_score>/100 — <certification_level> |
| 67 | +Failing: <N> findings (<N1> Tier 1, <N2> Tier 2, ...) |
| 68 | +``` |
| 69 | + |
| 70 | +If no failing findings, congratulate the user and stop. |
| 71 | + |
| 72 | +Otherwise ask: |
| 73 | + |
| 74 | +> "Fix applicable findings automatically, or review each one individually? |
| 75 | +> **auto** (default) — apply self-contained fixes immediately; prompt only when input is needed |
| 76 | +> **review** — prompt yes/skip/defer/quit for every finding" |
| 77 | +
|
| 78 | +Default to **auto** if the user says yes, presses Enter, or says "fix everything". |
| 79 | + |
| 80 | +## Step 5: Work through findings |
| 81 | + |
| 82 | +Work only through `status == "fail"` findings. Skip `not_applicable` and `pass` silently. |
| 83 | + |
| 84 | +**Sort order:** ascending tier, then descending `attribute.default_weight` within each tier. |
| 85 | + |
| 86 | +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. |
| 87 | + |
| 88 | +### Auto mode |
| 89 | + |
| 90 | +Apply each fix without prompting **unless**: |
| 91 | + |
| 92 | +- The fix requires project-specific input (CI platform, package ecosystem) |
| 93 | +- The finding might not apply to this repo type — present it and ask whether to apply or skip |
| 94 | + |
| 95 | +**Skip without prompting:** ADRs, design intent, architecture decisions — these require human rationale. Note them in the final summary. |
| 96 | + |
| 97 | +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. |
| 98 | + |
| 99 | +After processing, list what was applied, prompted, and skipped, then proceed to Step 6. |
| 100 | + |
| 101 | +### Review mode |
| 102 | + |
| 103 | +For each finding: |
| 104 | + |
| 105 | +``` |
| 106 | +[Tier <N>] <attribute.name> — <score>/100 |
| 107 | +Evidence: <evidence items> |
| 108 | +
|
| 109 | +Remediation: <remediation.summary> |
| 110 | +
|
| 111 | +Apply this fix? [yes / skip / defer / quit] |
| 112 | +``` |
| 113 | + |
| 114 | +**yes** — apply the fix, then move to the next finding. |
| 115 | +**skip** — move on; do not revisit. Use this if the finding doesn't apply to this repo. |
| 116 | +**defer** — note it; surface again after re-run. |
| 117 | +**quit** — stop immediately. |
| 118 | + |
| 119 | +**ADR and design intent findings:** Do not use JSON remediation. Ask instead: |
| 120 | + |
| 121 | +> "Do you have any architectural decisions worth capturing? Describe the decision and rationale — I'll write the ADR. Skip to add manually later." |
| 122 | +
|
| 123 | +Write only if the user provides input. Never invent rationale. |
| 124 | + |
| 125 | +### `agent_instructions` finding (both modes) |
| 126 | + |
| 127 | +Generate `AGENTS.md` and `CLAUDE.md` inline — do not delegate to another skill. |
| 128 | + |
| 129 | +**Scan the repo for commands:** |
| 130 | +- `package.json` → `scripts` entries (build, test, lint, typecheck, dev) |
| 131 | +- `Makefile` / `GNUmakefile` → targets |
| 132 | +- `pyproject.toml` → `[tool.pytest]`, `[tool.ruff]`, `[tool.mypy]`, `[project.scripts]` |
| 133 | +- `.github/workflows/*.yml` → `run:` steps containing test/lint/build/typecheck keywords |
| 134 | + |
| 135 | +**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. |
| 136 | + |
| 137 | +**If not RHDH (or RHDH context doesn't cover it):** ask these three questions one at a time: |
| 138 | +1. "What are 2-3 conventions an agent couldn't discover by reading the code? Skip if none." |
| 139 | +2. "Any non-obvious architectural decisions or places where things live unexpectedly? Skip if obvious." |
| 140 | +3. "Any commit format, CI checks, or PR conventions agents should know? Skip if standard." |
| 141 | + |
| 142 | +Write `AGENTS.md`: |
| 143 | + |
| 144 | +```markdown |
| 145 | +# <repo-name> |
| 146 | + |
| 147 | +## Build & Test Commands |
| 148 | +- Build: `<command>` |
| 149 | +- Test all: `<command>` |
| 150 | +- Test single file: `<command>` |
| 151 | +- Lint: `<command>` |
| 152 | +- Type check: `<command>` |
| 153 | + |
| 154 | +## Key Conventions |
| 155 | +<from scan + questions/rhdh_context> |
| 156 | + |
| 157 | +## Architecture |
| 158 | +<from questions/rhdh_context — omit if nothing to say> |
| 159 | + |
| 160 | +## PR Conventions |
| 161 | +- Agent-assisted commits should include an `Assisted-by: <model>` footer |
| 162 | +<from questions> |
| 163 | +``` |
| 164 | + |
| 165 | +Write `CLAUDE.md` with exactly: `@AGENTS.md` |
| 166 | + |
| 167 | +Omit any section — including its header — where there is nothing to say. Do not invent content. |
| 168 | + |
| 169 | +### Applying other fixes (both modes) |
| 170 | + |
| 171 | +Use `remediation.steps`, `remediation.commands`, and `remediation.examples` from the JSON. Do not invent steps beyond what the JSON provides. |
| 172 | + |
| 173 | +## Step 6: Re-run and present results |
| 174 | + |
| 175 | +```bash |
| 176 | +REPORT_DIR=$(mktemp -d) # on Windows: use %TEMP% or Python tempfile |
| 177 | +uvx --from git+https://github.com/ambient-code/agentready agentready -- assess \ |
| 178 | + -o "$REPORT_DIR" \ |
| 179 | + <path> |
| 180 | +``` |
| 181 | + |
| 182 | +Show before/after: |
| 183 | + |
| 184 | +``` |
| 185 | +Before: <old_score>/100 (<old_certification_level>) |
| 186 | +After: <new_score>/100 (<new_certification_level>) |
| 187 | +
|
| 188 | +Remaining failures: <N> findings |
| 189 | +``` |
| 190 | + |
| 191 | +If remaining failures (including deferred), ask: "Would you like to continue addressing the remaining findings?" If yes, repeat Step 5. |
| 192 | + |
| 193 | +## Batch mode |
| 194 | + |
| 195 | +When the user selects batch assessment: |
| 196 | + |
| 197 | +1. Ask: "What directory are your RHDH repos cloned into? (e.g. `~/git`)" |
| 198 | +2. Find subdirectories that are git repos: |
| 199 | + |
| 200 | +```bash |
| 201 | +find <dir> -maxdepth 2 -name ".git" -type d | sed 's|/.git||' |
| 202 | +``` |
| 203 | + |
| 204 | +3. For each, check if the remote URL matches a repo in `rhdh-repos.md`. Assess only matching repos. |
| 205 | +4. Run the assessment on each matched repo (Step 3) and collect results. |
| 206 | +5. Present a summary table: |
| 207 | + |
| 208 | +``` |
| 209 | +Repo Score Level Failing |
| 210 | +rhdh 72/100 Bronze 4 |
| 211 | +rhdh-operator 45/100 Needs Improvement 11 |
| 212 | +rhdh-plugins 88/100 Silver 1 |
| 213 | +``` |
| 214 | + |
| 215 | +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. |
| 216 | + |
| 217 | +## Gotchas |
| 218 | + |
| 219 | +- 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. |
| 220 | +- Do not output the report to the repository directory — use the temp dir to avoid polluting the working tree. |
| 221 | +- `not_applicable` findings reflect the detected language stack; do not mention them unless the user asks. |
| 222 | +- Deferred findings surface again after the re-run. |
| 223 | +- Never invent rationale for ADRs or design docs. In auto mode, skip them. In review mode, ask for rationale before writing anything. |
| 224 | +- In batch mode, only assess repos whose remote URL matches `rhdh-repos.md` — do not assess unrelated repos in the same directory. |
| 225 | +- `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. |
0 commit comments