Harmonia Repo Ready

Is an AI-built repository ready to hand off or release? Repo Ready scans a repository and returns a 0–100 readiness score, a tier, release blockers and the fixes in order of pain. The core audit runs locally and does not upload your source code.

· harmoniaready.dev · Install · Run · Samples · Product status

The self-audit badge is a generated result for this repository, not a general claim about every build. Treat it as current only when CI is green.

Product boundary

This repository contains Repo Ready, a repository-readiness audit product. It measures and reports. It does not modify source files, auto-fix findings, change the audited scope or issue a full business/product verdict.

Public slash commands are diagnostic views over the same audit result. Active commands are implemented and included in the local CLI. Roadmap commands are listed as planned in the canonical registry and are not executable until they have real implementations and acceptance tests.

What it checks

Available now

• committed secret and credential shapes,
• missing or weak tests,
• missing CI and deploy signals,
• dependency pinning and lockfiles,
• README, licence and repository hygiene,
• TODO debt, junk files and dead-weight directories,
• optional git-history secret scan,
• optional delegation to gitleaks or trufflehog,
• optional offline README-claim check (--check-promises).

Repo Ready checks readiness signals. It does not run the audited application or prove that its business logic is correct. A clean score means the repository is organised and reviewable, not that software has achieved spiritual purity.

Planned

• before/after comparison of two stored audit JSON snapshots,
• verified-fix validation against a specific previous finding,
• W3 behavioural checks: build, tests and process startup in the user's CI.

Check the machine-readable command status with:

harmonia-ready registry --json

Install

Requirements: Python 3.11 or newer and pipx.

Public beta status: source version 1.0.0-beta.3 is on main. The matching GitHub release tag and PyPI publication are not live yet, so install from Git:

pipx install "git+https://github.com/nikodemklasik-code/Harmony-2.o.git@main"
pipx ensurepath

When the release is published, the stable commands will become:

pipx install harmonia-ready
# GitHub Action consumers will be able to use @v1

Run

harmonia-ready audit .                      # terminal report
harmonia-ready audit . --md REPORT.md       # Markdown
harmonia-ready audit . --json report.json   # machine-readable JSON
harmonia-ready audit . --html report.html   # standalone HTML
harmonia-ready audit . --sarif report.sarif # SARIF 2.1.0
harmonia-ready audit . --fail-under 85      # CI gate
harmonia-ready audit . --scan-history       # optional git-history scan
harmonia-ready audit . --deep-secrets       # delegate to gitleaks/trufflehog
harmonia-ready audit . --check-promises     # README claims: present/stub/missing
harmonia-ready audit . --qc-sense           # optional configured remote sense check
harmonia-ready audit . --goal handoff       # first_user/investor_ready/recruiter/handoff
harmonia-ready audit . --profile security   # filter the rendered view

Public diagnostic views:

harmonia-ready command "/quick_score" .
harmonia-ready command "/full_error_report" .
harmonia-ready command "/estimate_repo" .
harmonia-ready command "/fix_guidance" .
harmonia-ready command "/code_handoff" .
harmonia-ready command "/production_closure_plan" .
harmonia-ready command "/release" .
harmonia-ready registry --check

All active local command views are included. The CLI does not sell feature unlocks by command name.

Output

Repo Ready returns:

• score 0–100,
• tier: ready, almost, prototype or mockup,
• milestone map K0–K8,
• findings with severity and confidence,
• top fixes ordered by pain,
• release and handoff gates,
• repair-effort units (critical ×5, important ×3, info ×1).

Repair-effort units are not the hosted platform's scan credits. The names are kept distinct in the product documentation because one word was apparently not enough trouble for humanity.

Hosted credits

The local CLI audit is included with the package. The hosted /rr service sells usage credits at a flat £0.20 per scan credit:

Hosted action	Credits	Price
Run scan and store full report	5	£1
Export a stored report as signed PDF	20	£4

There are no per-report-view unlocks. Subscription plans are monthly credit packs. See docs/PRODUKT.md.

GitHub Action

name: Repo Ready
on: [pull_request]
permissions:
  contents: read
  pull-requests: write
jobs:
  repo-ready:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: nikodemklasik-code/Harmony-2.o@main
        with:
          fail-under: "85"
          # extra-args: "--check-promises --goal handoff"

The action writes one sticky PR comment, a job summary and a pass/fail status. Public-repository PR comments are redacted by default; the full finding list stays in the job summary unless public-report: true is explicitly enabled.

Security and privacy

• The core audit is local and has no telemetry.
• Reported secrets are identified by type and path; values are never printed.
• Symlinks are skipped.
• Git file enumeration neutralises repository-local core.fsmonitor execution.
• File count, file size, response size and memory use are bounded.
• The local bridge binds to loopback and applies Host/Origin controls.
• The MCP server can be confined with HARMONIA_MCP_ROOT.
• The optional remote sense check sends a bounded README excerpt and audit facts, never source files or secret values.

Repo Ready is not a replacement for CodeQL, Semgrep, gitleaks, trufflehog, Dependabot or a human review. It answers a different question: is this repository in a state a competent reviewer could accept without spending the afternoon excavating it?

Integrations

• CLI and GitHub Action,
• MCP server: harmonia-ready-mcp,
• local bridge: harmonia-ready serve,
• browser extensions and userscript,
• VS Code/Cursor/Windsurf extension,
• hosted /rr web application with accounts, credits, history and signed PDF.

MCP example:

{
  "mcpServers": {
    "harmonia-ready": {
      "command": "harmonia-ready-mcp"
    }
  }
}

Documentation

• Product canon
• Status, roadmap and pricing
• Release and operations
• Report schema
• Samples
• Changelog

Licence

Source-available, not open source. Reading or running this repository does not grant rights to copy, modify, redistribute or host it as a competing service. See LICENSE. Security and licensing contact: support@multivohub.com.