ai-readiness-audit

An interactive CLI that scores a business's AI readiness and generates a branded Markdown/HTML report with tailored recommendations.

Most businesses that want to "do something with AI" have no idea whether their data, processes, tooling, or team are actually ready for it — and they don't know where to start. ai-readiness-audit turns that fuzzy conversation into a structured, repeatable assessment. Answer a dozen plain-English questions and get back a scored report you can hand to a client (or run on your own business) in under two minutes.

It's the digital version of the very first thing a consultant does on a new engagement — packaged so anyone can run it and see the results.

What you get

• A guided questionnaire — 12 questions across four dimensions: data maturity, process & workflow, tooling & tech, and team & strategy.
• A scored readiness tier — an overall band (Nascent → Developing → Ready → Advanced) plus a per-dimension breakdown.
• Actionable recommendations — concrete next steps tailored to each dimension's score, and a prioritized list focused on your weakest areas.
• A shareable report — clean Markdown and a standalone, print-to-PDF-ready HTML file. No headless browser, no external services.

Install & run

Requires Node.js 18+.

Run it directly with your package manager, no install needed:

# Interactive — walks you through the questions
pnpm dlx ai-readiness-audit
# or: npx ai-readiness-audit

Or add it to a project:

pnpm add -D ai-readiness-audit

Non-interactive mode

Score a saved answers file (YAML or JSON) — handy for scripting, CI, or re-running an assessment:

ai-readiness-audit --answers answers.yaml --name "Acme Co"

See examples/answers.example.yaml for the format (each question scored 0–3).

Options

-a, --answers <file>   Score answers from a YAML/JSON file (non-interactive).
-o, --out <basename>   Output file base name (default: derived from the name).
-f, --format <fmt>     Report format: md | html | both  (default: both).
-n, --name <business>  Business name shown on the report.
    --json             Print the scored result as JSON; do not write files.
-h, --help             Show help.
-v, --version          Show version.

Example output

Running against the sample answers prints a summary to the terminal…

Overall readiness: Developing (47%)
  █████░░░░░ 47%

  Data maturity        ████░░░░░░ 44%  Developing
  Process & workflow   ████░░░░░░ 44%  Developing
  Tooling & tech       ██████░░░░ 56%  Developing
  Team & strategy      ████░░░░░░ 44%  Developing

…and writes a full report. Here's an excerpt of the Markdown:

# AI Readiness Report — Acme Co

**Overall readiness: Developing (47%)**

_Foundations are forming — targeted improvements will unlock AI._

## Your top priorities

1. You have the building blocks in place. Prioritize connecting your systems
   and picking one high-value process to automate as a proof of concept.
2. Strengthen data maturity: Consolidate scattered spreadsheets into a shared
   source of truth (a CRM or database).
3. Strengthen process & workflow: Turn your informal notes into checklists or
   standard operating procedures.

The HTML report is the same content, styled and ready to print to PDF from any browser (File → Print → Save as PDF).

How scoring works

Each of the four dimensions has three questions, scored 0–3. A dimension's percentage is its earned points over its maximum; the overall score is the sum across all dimensions. Percentages map to tiers:

Score	Tier
0–39	Nascent
40–59	Developing
60–79	Ready
80–100	Advanced

Recommendations are selected per dimension based on its tier, and the top priorities surface your two weakest dimensions first.

Programmatic API

The scoring and report generation are exported as a typed library:

import {
  scoreAudit,
  generateMarkdown,
  generateHtml,
  DEFAULT_META,
  type Answers,
} from 'ai-readiness-audit';

const answers: Answers = {
  data_storage: 1,
  data_quality: 1,
  data_access: 2,
  process_docs: 1,
  process_manual: 1,
  process_automation: 2,
  tooling_stack: 2,
  tooling_integration: 1,
  tooling_api: 2,
  team_leadership: 2,
  team_experience: 1,
  team_budget: 1,
};

const result = scoreAudit(answers);
console.log(result.overall); // { earned, max, percentage, tier }

const markdown = generateMarkdown(result, { ...DEFAULT_META, businessName: 'Acme Co' });

QUESTIONS, DIMENSIONS, and validateAnswers are exported too, so you can build your own front-end on the same model.

Development

pnpm install
pnpm dev          # run the CLI from source
pnpm test         # run the Vitest suite
pnpm run lint     # ESLint
pnpm run typecheck
pnpm run build    # bundle to dist/ with tsup

License

MIT © Rick (@brutusdev0)