arthai-marketplace

/calibrate

Deep-learn a project and configure the full toolkit — scans code patterns, recommends MCP servers/agents/skills/workflows, installs everything. The single entry point for project adaptation.

Synopsis

/calibrate [full|rescan|recommend|status|best-practices]

When to use it

First time the toolkit is installed on a project — run plain /calibrate
After the project evolves significantly (new framework, new service, >20% more files, or >2 weeks since last calibration) — /calibrate rescan. Or just run /calibrate with no arguments — it auto-detects and rescans if already calibrated.
To see suggestions without installing anything — /calibrate recommend
Not for: a quick CLAUDE.md refresh — that’s /scan; or updating the toolkit itself — see the FAQ update flow

Prerequisite: CLAUDE.md must exist and be complete (no  placeholders). If it’s missing or incomplete, /calibrate automatically runs /scan first.

Quickstart

/calibrate

What you’ll see: a mode line explaining which mode was picked and why, then the calibration phases run, ending in a recommendations report (MCP servers, toolkit categories, workflows, custom agents/skills) and an install prompt. On completion it writes .claude/project-profile.md and advises starting a fresh session.

Examples

/calibrate                                  # full calibration first time; auto-rescan if already calibrated
/calibrate full                             # force a full calibration even if already calibrated
/calibrate rescan                           # diff against the existing profile, show what changed
/calibrate rescan --skip-debt               # rescan without the conditional tech-debt audit
/calibrate recommend                        # read-only — show recommendations, install nothing
/calibrate status                           # current calibration state, no sub-agents
/calibrate best-practices --source local    # extract best practices from your codebase
/calibrate best-practices --source industry # generate industry best practices for your stack

What it does

Phase 0 — mode detection (inline): checks for .claude/project-profile.md. No profile → full calibration; profile present → auto-rescan. Shows a mode line (with a cost ladder of the alternatives) so you can switch. Also verifies CLAUDE.md has the toolkit managed block and runs /scan first if CLAUDE.md is missing or still has  placeholders.
Phase 1 — scan: a scanner agent deep-reads the project — platform, architecture patterns, coding conventions, testing patterns, domain model, integrations, environments.
Phase 2 — evaluate: an evaluator agent scores every toolkit agent, skill, and hook against the scan and identifies gaps and recommended workflows.
Phase 3 — profile: a profiler agent writes .claude/project-profile.md (diff mode on rescan — only changes, manual sections preserved).
Phase 4 — recommend (user-confirmation checkpoint): presents the report, then asks via AskUserQuestion: Install all / Pick items (a multi-select follow-up) / Skip (profile only). This prompt always fires — installs require your approval.
Phase 5 — install (parallel): installer applies the approved items; a knowledge agent seeds .claude/knowledge/; a best-practices agent writes .claude/knowledge/shared/best-practices.md.
Phase 5b — build knowledge graph (inline): after the three Phase 5 agents return, the orchestrator runs kg-ingest.sh --rebuild to index the knowledge base into a queryable graph. This is what lets downstream skills (/planning, /implement, /fix, /qa, /pr, /perf, /ci-fix, and others) pull ranked, relevant context instead of reading the whole knowledge base every time — it’s why calibration is foundational to the rest of the toolkit. Non-blocking: if the knowledge-graph skill isn’t installed, calibration still succeeds and those skills fall back to full KB reads.
Phase 6 — verify (inline): confirms MCP servers in settings, categories installed, profile and knowledge base written, then prints the completion report.
Phase 7 — completion verification: an independent verifier agent reports PASS / GAPS FOUND / INCONCLUSIVE — gaps don’t block; you decide whether to rerun.

Rescan additionally integrates older calibrate-created agents/skills into workflows (asks yes/no/pick — a user-confirmation checkpoint) and may run a conditional tech-debt audit based on drift signals (--force-debt / --skip-debt to override). If a phase fails, dependent phases are skipped and the profile is marked partial — calibration still completes with what it has.

Agents spawned

Agent	Model tier	Role
calibrate-scanner	haiku	Deep project scan
calibrate-evaluator	haiku	Scores toolkit fit, finds gaps
calibrate-profiler	haiku	Writes `.claude/project-profile.md`
calibrate-installer	sonnet	Installs approved items
calibrate-knowledge	haiku	Seeds the knowledge base
calibrate-best-practices	sonnet	Writes best-practices doc
completion-verifier	sonnet	Independent completion check

(Tiers are the defaults — your model-policy.yml governs the actual choice.)

Cost & running it cheaply

The sub-agents above are Haiku/Sonnet only — none run at Opus. Their tiers are controlled by model-policy.yml, not your session model — switching /model has no effect on sub-agent spawns.

The only place Opus can enter is the Claude Code session that drives the skill — the orchestrator’s own inline work (Phase 0 mode detection, Phase 4 recommendations, Phase 6/7 verification). That session runs at your Claude Code model — set in ~/.claude/settings.json (the "model" key) or switched live with /model. It is not controlled by the toolkit, so if your session is on Opus, the orchestrator’s inline steps run on Opus even though every spawned agent stays Haiku/Sonnet.

To minimize Opus use: check model-policy.yml first — if it already specifies Sonnet for all agents (the default), sub-agents already run Sonnet regardless of your session model, and there’s nothing more to gain there. If your session itself is on Opus and you want to cut cost on the orchestrator’s inline work too, switch before running:

/model sonnet     # orchestrator's inline work → Sonnet; sub-agents unaffected either way
/calibrate
/model opus       # switch back afterwards if you like

Model tier isn’t the dominant cost, though — the scan volume is (the Haiku scanner reading many files). The single biggest saving is simply not running calibrate on an Opus session. For the wider cost picture see Configuration → Context budget, and watch a run live — cost by model/skill/owner — in Arth Intelligence.

Output & artifacts

.claude/project-profile.md — architecture, conventions, domain model
.claude/knowledge/ — seeded knowledge base (incl. shared/best-practices.md)
.claude/settings.json — recommended MCP servers added (never removed)
.claude/agents/, .claude/skills/ — custom agents/skills created as regular files
A final report plus a context tip: calibration is the heaviest context operation — start a fresh session after it finishes. The phases fill your session with intermediates (scanner output, KB reads, evaluator matrices) that have no further runtime value once the files are written — everything of value is already saved in .claude/project-profile.md and .claude/knowledge/, so clearing context loses nothing

Troubleshooting

Problem	Fix
`/calibrate recommend` errors about a missing profile	Recommend mode requires an existing `project-profile.md` — run `/calibrate` first
New MCP servers don’t appear	Restart Claude Code after calibration adds MCP servers
`/calibrate best-practices` errors about `--source`	The flag is required — pass `--source local` or `--source industry`
Report says `calibration_status: partial`	A phase failed and dependents were skipped — re-run `/calibrate full`

/scan — lighter CLAUDE.md population; calibrate runs it when needed
/onboard — session briefing; hints at calibrate when no profile exists
/setup — bootstraps a project from scratch; calibrate is the natural follow-up