Getting started

1. Run one exact-version trial

cd /path/to/your-project
npx --yes marucheck@0.3.0 --version
npx --yes marucheck@0.3.0 init

This is the fastest path for one local trial. Initialization creates the .maru/ workspace without overwriting existing configuration. It also manages ignore rules for generated plans, run artifacts, and local connection credentials.

2. Pin it before regular use

npm install --save-dev --save-exact marucheck@0.3.0
npx --no-install maru init

Pinning writes the verifier into package.json and package-lock.json, so local contributors and CI execute the same release. Use npx --no-install maruafter installation to prevent an implicit download.

3. Inspect the repository

npx --no-install maru doctor
npx --no-install maru scan

Doctor reports missing prerequisites explicitly. Scan records detected routes, tests, dependencies, CI, and source structure in .maru/generated/project-scan.json. Neither command silently installs project tools. Commit .maru/maru.yml, reviewed contracts, and QA memory; do not commit .maru/generated/, .maru/artifacts/, or .maru/connection.env.

4. Start with one feature contract

npx --no-install maru contract create --from requirements.md
npx --no-install maru contract validate
npx --no-install maru contract approve <contract-id> --by <owner>

Use a small requirements file for the feature being changed, not the entire product. Draft creation does not approve anything. Review the generated YAML under .maru/contracts/ before an accountable owner approves it. Draft and review policies remain advisory; approval is what activates their blocking requirements.

5. Verify the current change

npx --no-install maru risk --diff
npx --no-install maru plan --diff
npx --no-install maru verify --diff

Review the risk reasons and plan before execution. Verification runs only selected tools already installed in the project, prints a passed or blocked gate, and writes the complete report under .maru/artifacts/runs/<run-id>/report.json. A missing adapter is reported as unavailable or inconclusive, never as a pass.

6. Connect the agent you already use

Follow the MCP connection guide for Codex, Claude Code, or Cursor. Once connected, the coding agent can call MaruCheck's bounded local tools instead of scraping terminal output.

1. BuilderYour existing coding agent implements the change.
2. VerifierMaruCheck deterministically checks contracts, risk, tests, and evidence.
3. ChallengerA fresh thread or subagent proposes failure scenarios for risky work.
4. DecisionExecuted checks and evidence—not the agent's opinion—pass or block.

7. Add shared infrastructure when useful

1. Optionally connect a dashboard project, save its token in the ignored connection file, and upload one completed report.
2. Add the GitHub pull-request gate only after the local workflow and contract policy behave as intended.
3. Use drift protection, QA memory, Challenger review, and mutation verification where the risk justifies the additional review or execution time.