Help us improve
Share bugs, ideas, or general feedback.
npx claudepluginhub bri-stevenski/oracle-test-ai-agent --plugin oracleHow this skill is triggered — by the user, by Claude, or both
Slash command
/oracle:oracle-setup-harnessThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> Configure the Harness Engineering guardrails in a new Oracle
Provides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.
Share bugs, ideas, or general feedback.
Configure the Harness Engineering guardrails in a new Oracle project (or a fork). Installs the harness CLI, initialises the config, wires up CI workflows, and verifies all gates pass on a clean repository.
harness.config.json directlyVerify Node.js is available (harness CLI requires it):
node --version
Version 18 or later is required.
Verify Python is available (security ledger script):
python3 --version
Version 3.11 or later is required.
Confirm the repo has a harness.config.json at the
root. If it doesn't, the harness is not yet configured —
continue to Phase 2. If it does, validate it first:
npx --yes -p @harness-engineering/cli harness validate
If validation passes, the harness is already set up. Stop here unless re-alignment is the goal.
Initialise the harness from the repo root:
npx --yes -p @harness-engineering/cli harness init
This creates harness.config.json with default gates and
generates the .harness/ hooks directory.
Review the generated harness.config.json. The defaults
are sensible, but confirm:
layers matches the project's actual package structure
(for Oracle: llm, core, cli)entrypoints lists the correct top-level packagestelemetry and adoption settings match team policyInspect .harness/hooks/. The hooks directory contains
scripts that run locally on git events. Review each file
briefly — they should not require network access outside
the harness telemetry endpoint.
Check which workflows already exist:
ls .github/workflows/
Required workflows for a full harness setup. Each
should exist as a .yml file in .github/workflows/:
harness.yml — core phase-gate checksharness-architecture.yml — layer dependency validationharness-quality.yml — quality and integrity checksharness-security.yml — security scan + ledger refreshdocs-lint.yml — markdown formatting enforcementIf any are missing, copy them from an upstream Oracle reference install or generate them:
npx --yes -p @harness-engineering/cli harness \
generate-workflows
Confirm harness-security.yml refreshes the ledger.
The final steps of the security job must run the ledger
script and commit if changed. Without this, the security
ledger goes stale and the Quality gate fails.
Confirm docs-lint.yml covers all doc paths. The
workflow's paths filter should include:
docs/**agents/**AGENTS.mdSet required permissions. Workflows that commit
back to the repository need contents: write:
permissions:
contents: write
This applies to harness-security.yml at minimum.
Run the security scan to create the initial ledger:
npx --yes -p @harness-engineering/cli harness check-security
python3 scripts/security_ledger.py
Commit the generated baseline files:
git add harness.config.json .harness/ \
.harness/security/timeline.json \
docs/SECURITY_LEDGER.md
git commit -m "chore: initialise harness configuration"
Push and confirm all CI gates pass on the resulting commit before calling setup complete.
Open a pull request (or push to the configured branch) to trigger CI.
Check each workflow:
If any gate fails: Read the error, fix the root cause, push again. Do not suppress gates or skip hooks to make CI green — fix the actual issue.
Log to docs/ORACLE_STATE.md that harness setup was
completed, including the date and commit SHA.
harness.config.json — Layer rules, entrypoints,
telemetry/adoption settings. Source of truth for all
harness gates..harness/hooks/ — Local git hooks generated during
harness init. Committed so all contributors share them..github/workflows/ — CI workflows that run the harness
gates on every PR.scripts/security_ledger.py — Regenerates
docs/SECURITY_LEDGER.md from .harness/security/timeline.json.
Must be run after every security scan.docs/ORACLE_STATE.md — Project ledger. Log setup
completion here.harness validate exits cleanly with no violationsdocs/SECURITY_LEDGER.md) exists and
is not stale.harness/hooks/ is committed and present in the repodocs/ORACLE_STATE.md| Rationalization | Why It Is Wrong |
|---|---|
"CI is red but the code is fine, I'll add --no-verify" | Skipping hooks defeats the entire purpose of the harness. Fix the root cause. |
| "I'll set up the workflows later — the config is good enough" | A config with no CI enforcement is ornamental. The gates only protect the team when they run on every PR. |
| "The security ledger step seems redundant — the scan already ran" | The scan writes to a JSON timeline; the ledger script produces the human-readable summary. Both are needed. |
| "I'll commit the hooks directory but not review the files" | Hook files run on every developer's machine. Review them before committing — they're executable scripts. |
Scenario: cap-oracle is a new fork of oracle-test-ai-agent.
It has no harness config yet.
Steps:
harness init.harness.config.json — layers match llm, core,
cli. Entrypoints set to agent.ORACLE_STATE.md.Scenario: A harness CLI update added a new hook file to
.harness/hooks/. The local copy doesn't have it.
Steps:
npx --yes -p @harness-engineering/cli harness update..harness/hooks/ — confirm the new
file is expected.harness init fails or produces unexpected output:
Check the harness CLI version. A major version mismatch
between the CLI and the harness.config.json schema is the
most common cause.