AI coding assistants can produce code quickly, but speed does not tell you whether a repository can guide, observe, and constrain that work. A project may have instructions and still lack tests, feedback, or a deterministic way to detect regressions.
The Harness Score Live Demo is a small open-source repository that turns this problem into a runnable lesson. It is an interactive presentation in Brazilian Portuguese, backed by real repository artifacts and scripts. You can run the presentation, inspect the checks, and measure the repository with Harness Score.
This tutorial uses the current main branch and the repository's documented commands. The project is public, non-archived, non-forked, MIT licensed, and currently reports version 1.0.0 in package.json.
What you will learn
The demo targets Harness Score level L3, called Sensing. Its repository includes project guidance, scoped rules, skills, commands, tests, linting, type checking, a production build, pre-commit feedback, and CI feedback.
It deliberately does not install agent-runtime hooks. That missing layer is the teaching point: a written rule can describe behavior, while a hook can observe or block a tool action outside the model.
Prerequisites
You need Git, Node.js 22 or a compatible current Node.js release, npm, and a terminal. You do not need an API key or an AI provider account to run the presentation or repository scan.
1. Install and run the presentation
Clone the repository and install its locked dependencies:
git clone https://github.com/paladini/harness-score-live-demo.git
cd harness-score-live-demo
npm ci
Start the Vite development server:
npm run dev
Open the local URL printed by Vite. The README says that the presentation supports Arrow keys, Page Up, Page Down, Space, Home, and End. An overview button exposes all eleven slides.
The presentation uses a cockpit metaphor. It covers the problem around an AI coding model, the L0 to L4 maturity scale, the six Harness Score dimensions, scoped instructions, deterministic sensors, runtime hooks, and a live scan.
2. Run the repository checks
The repository groups its local quality checks in npm run check:
npm run check
The script runs four stages:
npm run lint
npm run typecheck
npm test
npm run build
The package uses Biome for linting, TypeScript's compiler for strict checks, Node's built-in test runner, and Vite for the production build. These checks answer a different question from the maturity scan: they test whether the demo itself remains healthy.
On a fresh Windows checkout, optional native dependency installation can affect the Biome executable. If npm run lint reports that a platform package such as @biomejs/cli-win32-x64 is missing, treat that as an environment or npm optional-dependency problem and investigate the installation before claiming that the repository checks passed. The CI workflow runs on Ubuntu and uses Node.js 22.
3. Measure the harness
The repository pins Harness Score 1.5.1 as a development dependency. Run the scan through the package script:
npm run scan
The current checkout reports a score of 91/108, or 84%, at maturity level L3. The scan breaks the result into dimensions:
- Context and Guides: 20/20.
- Skills and Commands: 17/17.
- Hooks and Guardrails: 0/14.
- Sensors and Feedback: 20/20.
- CI Feedback: 14/14.
- Hygiene and Safety: 20/23.
The exact score is evidence about this repository at the scanned revision, not a universal grade for every project. A different Harness Score version, file set, or command scope can change the result.
4. Turn the score into a gate
The stricter command applies a minimum maturity requirement:
npm run scan:gate
That script expands to:
harness-score . --min-level 3
The command succeeds when the repository reaches at least L3. It does not claim that the project is L4 or that an AI agent is safe to run without review. It is a guardrail for a measurable repository property.
The CI workflow runs this gate after checkout, Node.js setup, dependency installation, linting, type checking, tests, and the production build:
- name: Keep the demo at L3 or higher
run: npm run scan:gate
That ordering is useful. A repository should pass its ordinary software checks before a maturity score becomes a required status signal.
Why L3 stops before L4
The scan reports six missing improvements in this current repository. Five are hook-related: there is no parseable hook configuration, no registered hook events, no gate hook for risky operations, no feedback hook, and no committed hook script. The sixth is an MCP hygiene check because the repository has no MCP configuration.
This boundary is more informative than adding a label such as "AI-ready". L3 means the project has deterministic sensing and CI feedback. L4 requires the harness to participate in the agent loop with runtime guardrails and feedback.
The repository intentionally leaves that gap visible. You can use the demo to explain why AGENTS.md and scoped rules are valuable, then ask what should happen when an agent ignores a written rule. A pre-tool gate can deny or ask for approval; a post-tool hook can format or test changed files.
Deployment to GitHub Pages
The repository includes a separate Pages workflow. It builds the Vite output and deploys the dist directory:
- run: npm run build
- uses: actions/configure-pages@v6
- uses: actions/upload-pages-artifact@v5
with:
path: dist
The deployment job uses actions/deploy-pages@v5 and depends on the build job. To use the workflow in your own fork, enable GitHub Pages with GitHub Actions as the source and review the workflow permissions before pushing.
The live presentation linked by the project is hosted at paladini.io/harness-score-live-demo. The repository is the source and evidence; the public page is the rendered presentation.
Troubleshooting and limits
The scan cannot find the command. Run npm ci first so the local harness-score binary exists, or invoke the package through the repository's npm script.
The gate fails below L3. Read the improvement list rather than changing the threshold blindly. The report names missing evidence and links to relevant Harness Score guidance.
The presentation builds but the score changes. Check the commit, installed package version, and scan scope. The score is derived from repository evidence, so configuration changes can change the result.
The Pages deployment is blocked. Verify that Pages is enabled, the workflow has pages: write and id-token: write, and the build job produced dist.
The scan is not a security certification, an agent benchmark, or proof that a project will behave safely under every prompt. It is a repository-grounded measurement tool. Human review and project-specific threat modeling remain necessary.
FAQ
Does Harness Score execute an AI agent?
No. This demo scans repository artifacts and reports maturity evidence. It does not replace an agent runtime or evaluate model quality.
Why keep hooks out of an L3 demo?
Because the missing hooks make the L3 to L4 boundary visible. The project can show sensors and CI feedback without pretending that written instructions are runtime enforcement.
Can I use the scan in another repository?
Yes, after installing Harness Score in that repository. Start with harness-score ., review the evidence, and add --min-level 3 only when the threshold matches your workflow.
Takeaway
The live demo turns harness engineering into something you can run, inspect, and measure. Start with ordinary checks, add the maturity scan, then treat missing hooks as an explicit design decision rather than an invisible assumption.
What would you add first to move this repository toward L4: a pre-tool gate, a post-edit feedback hook, or an MCP configuration with environment-based credentials?
Disclosure: I used AI assistance to organize and edit this tutorial. The commands, repository metadata, scan output, workflow, and limitations were checked against the current project checkout and linked primary sources.
Top comments (0)