agent-readiness-action

# agent-readiness-action

[![version](https://img.shields.io/github/v/release/alipajand/agent-readiness-action?label=version&color=blue)](https://github.com/alipajand/agent-readiness-action/releases)
[![tests](https://img.shields.io/badge/tests-112%20passing-brightgreen)](https://github.com/alipajand/agent-readiness-action/actions/workflows/ci.yml)
[![coverage](https://img.shields.io/badge/coverage-55%25-yellow)](https://github.com/alipajand/agent-readiness-action/actions/workflows/ci.yml)
[![CI](https://github.com/alipajand/agent-readiness-action/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/alipajand/agent-readiness-action/actions/workflows/ci.yml)
[![CodeQL](https://github.com/alipajand/agent-readiness-action/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/alipajand/agent-readiness-action/actions/workflows/codeql.yml)
[![license](https://img.shields.io/github/license/alipajand/agent-readiness-action?color=blue)](LICENSE)

## What it is

A GitHub Action that checks how ready a repository is for AI coding agents (Claude Code,
Cursor, Codex, Copilot, and similar). It bundles two deterministic engines:

- [agent-readiness-kit](https://github.com/alipajand/agent-readiness-kit) scores the
  repository from 0 to 100: instruction files, architecture notes, scripts, tests, safety
  boundaries, and more. Lockfiles, version pins, test runners, linters, and formatters are
  scored on the files of each detected ecosystem (Node.js, Python, Go, Rust). It prints a
  category breakdown in the log and job summary.
- [agent-context-doctor](https://github.com/alipajand/agent-context-doctor), with
  `context-audit: 'true'`, checks the instruction files themselves: placeholders, risky
  directives, contradictions, stale commands, pasted secrets, hidden Unicode, and risky
  Claude Code and MCP configuration such as `bypassPermissions`, hooks that run remote
  scripts, or third-party API endpoints.

It can fail the build below a score, block pull requests that lower the score, write a
Markdown report, and post a summary comment on pull requests.

Both engines are bundled into the action at pinned commits, so nothing is downloaded or
executed from a package registry at run time. There are no external API calls (other than
the optional PR comment), no telemetry, and no LLM calls.

## Why use it

- Catch missing or low-quality agent context (instruction files, architecture notes,
  setup docs) before it slows down day-to-day agent work.
- Catch instruction files and agent settings that steer agents toward unsafe changes or
  let them run commands without asking.
- Track the readiness score over time and gate pull requests on a minimum score or on
  any drop from the base branch.
- Give reviewers a concise, deterministic summary on each PR — a complement to human
  review, not a replacement for it.

## Quick start

```yaml
# .github/workflows/agent-readiness.yml
name: Agent Readiness Audit

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: alipajand/agent-readiness-action@v1
```

## Examples

### Basic audit

```yaml
name: Agent Readiness Audit

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: alipajand/agent-readiness-action@v1
```

### Fail below a minimum score

```yaml
- uses: alipajand/agent-readiness-action@v1
  with:
    min-score: '70'
    fail-on-threshold: 'true'
```

### Comment on pull requests

```yaml
permissions:
  contents: read
  pull-requests: write
  issues: write

steps:
  - uses: actions/checkout@v7
  - uses: alipajand/agent-readiness-action@v1
    with:
      comment-on-pr: 'true'
      min-score: '70'
      github-token: ${{ github.token }}
```

The action posts a single comment the first time and updates it on subsequent runs, so
there are no duplicate comments. It only updates a comment that starts with its hidden
marker and was written by a bot account, so pasting the marker into your own comment
does not make the action overwrite it. When commenting with a personal access token,
set `comment-author` to that account's login.

### Block pull requests that lower the score

```yaml
on:
  pull_request:

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0 # the base commit must be available
      - uses: alipajand/agent-readiness-action@v1
        with:
          baseline-ref: ${{ github.event.pull_request.base.sha }}
          max-score-drop: '0'
```

The action audits the base commit in a temporary git worktree, reports the change (`▼ -5 vs <sha>`) in the log, job summary, and PR comment, and fails when the score drops by more than `max-score-drop`.

### Also check the agent instruction files

```yaml
- uses: alipajand/agent-readiness-action@v1
  with:
    context-audit: 'true' # run the bundled agent-context-doctor
    context-fail-on: 'high' # fail on risky instructions, secrets, hidden characters, ...
```

With `context-audit`, the action also runs [agent-context-doctor](https://github.com/alipajand/agent-context-doctor) on the same path. Its score and top issues appear in the log, job summary, and PR comment. It honors the audited repository's `.acdrc`.

### Write a Markdown report artifact

```yaml
steps:
  - uses: actions/checkout@v7

  - uses: alipajand/agent-readiness-action@v1
    with:
      output: 'docs/agent-readiness-report.md'

  - uses: actions/upload-artifact@v7
    with:
      name: agent-readiness-report
      path: docs/agent-readiness-report.md
```

### Audit a subdirectory or monorepo package

```yaml
- uses: alipajand/agent-readiness-action@v1
  with:
    repo-path: './packages/web'
```

## Inputs

| Input               | Default | Description                                                                                                                                                                      |
| ------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `repo-path`         | `.`     | Path to the repository or subdirectory to audit. Relative paths are resolved from the GitHub Actions workspace root.                                                             |
| `min-score`         | `0`     | Minimum acceptable score (0–100). Checked when `fail-on-threshold` is `true`.                                                                                                    |
| `output`            | `''`    | Write a Markdown report to this path. Relative paths are resolved under `repo-path`, and the result must stay inside `repo-path`. The report is never written through a symlink. |
| `json`              | `false` | Echo the raw JSON audit output to the Actions log.                                                                                                                               |
| `comment-on-pr`     | `false` | Post or update a PR comment. Only runs on `pull_request` events. Requires a token with `pull-requests: write` and `issues: write`.                                               |
| `github-token`      | `''`    | Token for the PR comment, usually `${{ github.token }}`. Falls back to the `GITHUB_TOKEN` environment variable.                                                                  |
| `comment-author`    | `''`    | Only update an earlier summary comment written by this login. Defaults to any bot account.                                                                                       |
| `baseline-ref`      | `''`    | Git ref to compare against, usually `${{ github.event.pull_request.base.sha }}`. Audited in a temporary worktree; needs `fetch-depth: 0`.                                        |
| `max-score-drop`    | `''`    | Fail when the score is more than this many points below the `baseline-ref` score (`0` fails on any drop). Requires `baseline-ref`.                                               |
| `job-summary`       | `true`  | Write the audit summary to the workflow run's job summary.                                                                                                                       |
| `context-audit`     | `false` | Also check agent instruction files with the bundled agent-context-doctor.                                                                                                        |
| `context-fail-on`   | `''`    | Fail when agent-context-doctor finds an issue at or above `low`, `medium`, or `high`. Requires `context-audit`.                                                                  |
| `fail-on-threshold` | `true`  | Fail the step when the score is below `min-score`.                                                                                                                               |

## Outputs

| Output                | Description                                                                       |
| --------------------- | --------------------------------------------------------------------------------- |
| `score`               | Final agent-readiness score (0–100).                                              |
| `report-path`         | Absolute path of the written Markdown report, or empty when `output` was not set. |
| `passed`              | `"true"` when the score is at least `min-score`, otherwise `"false"`.             |
| `categories`          | JSON array of category scores: `id`, `label`, `score`, `maxScore`.                |
| `baseline-score`      | Score at `baseline-ref` (only when `baseline-ref` is set).                        |
| `score-delta`         | Score minus the baseline score (only when `baseline-ref` is set).                 |
| `c