What is arthai?

arthai is a development toolkit that turns Claude Code into a coordinated engineering team — specialized agents, slash-command workflows, and automatic guardrails, installed as Claude Code plugins and adapted to your codebase.

The problem it solves

Claude Code out of the box is one generalist assistant. It's powerful, but:

• Everything runs at premium cost. A file lookup costs the same model tier as an architecture decision.
• Workflows live in your head. Plan → implement → QA → PR is a sequence you re-type and re-forget every time, and steps get skipped.
• No guardrails. Nothing stops a destructive command, an accidental edit to a migration file, or a push to main.
• No visibility. When a session ends, you have no record of what the AI did, which agents ran, or what it cost.

What arthai adds

Who it's for

• Engineers shipping with Claude Code daily who want repeatable workflows instead of improvised prompting.
• Teams that care about cost — the toolkit routes routine work to cheaper models automatically.
• Anyone who needs an audit trail of what AI did in their codebase.

It also includes role-based flows (/welcome, /wizard) for non-engineers on the team.

What it is NOT

• Not a replacement for Claude Code — it's installed into Claude Code as plugins.
• Not a cloud service — everything runs locally; observability data never leaves your machine.
• Not all-or-nothing — install focused bundles (QA only, ops only, consulting only) or prime for everything.

How the pieces fit

Next steps

• Getting started — install in ~10 minutes
• Plugin catalog — pick a bundle
• Arth Intelligence — turn on the dashboard
• FAQ

Getting Started

New here? This guide takes you from nothing to a working toolkit in ~10 minutes (Steps 1–6), then observability (Step 7, optional), calibration (Step 8), and a fresh session (Step 9).

No toolkit — just the arth CLI? Do Steps 1–2, then Installing the Arth CLI. It gives you telemetry, Explain, and the Cloud Orchestrator from a terminal without the Claude Code toolkit.

Already installed? Skip the walkthrough — update via the FAQ update flow, connect another repo to observability via the Arth Intelligence guide, or fully remove it via the Uninstall guide.

Prerequisites

• Claude Code installed and working
• Node.js 22+ — for npx arthai-activate
• Git
• macOS or Linux (Windows via WSL)
• A valid Arth AI license key (ARTH-XXXX-XXXX-XXXX-XXXX)

Step 1: Get a license key and repo access

Email productive@getarth.ai with your GitHub username to request a license key.

You'll receive:

• A license key (ARTH-XXXX-XXXX-XXXX-XXXX)
• A collaborator invite to the arthai-marketplace private repo on GitHub

Accept the GitHub invite before continuing — Step 3 requires repo access.

Just want the no-toolkit CLI? If you're not using the Claude Code toolkit and only want the arth command (telemetry + Explain + Cloud Orchestrator from a terminal), do Steps 1–2 above, then jump straight to Installing the Arth CLI — you can skip the toolkit steps (3–7).

Step 2: Activate your key

Run this in your terminal (not inside Claude Code):

npx arthai-activate ARTH-XXXX-XXXX-XXXX-XXXXCopy

This stores your key at ~/.arthai/license. You only need to do this once.

Step 3: Add the plugin marketplace

Inside Claude Code:

/plugin marketplace add ArthTech-AI/arthai-marketplaceCopy

Step 4: Choose and install a bundle

Start with prime — the everything bundle. Includes all agents, skills, and hooks:

/plugin install prime@arthaiCopy

If you want a smaller, focused bundle instead, see the plugin catalog for all available bundles.

Step 5: Enable auto-updates

Run /plugin, open the Marketplaces tab, select arthai, and choose Enable auto-update. This keeps your toolkit up to date automatically — new agents, skills, and bug fixes land without manual intervention.

Step 6: Reload and verify

/reload-pluginsCopy

Then fully quit and reopen Claude Code. A running session loads its command list at startup, so a newly added command (e.g. /cloud-setup after an update) won't appear from /reload-plugins alone — only a full restart (quit the app/CLI completely, not /clear) rebuilds the command set. This is the most common reason a freshly installed skill "isn't there."

Step 7: Enable observability (optional)

You can skip this step and jump to Step 8: Calibrate. The toolkit works without observability. Come back here whenever you want a dashboard view of what Claude Code is doing — sessions, tool calls, agent spawns, cost.

New to this? Start with the Arth Intelligence guide — what the dashboard shows, why you'd want it, and what data stays on your machine. This step is the detailed install walkthrough.

⚠️ Experimental — limited preview. Observability is in active development. Expect rough edges, breaking changes between releases, and gaps in coverage. Feedback welcome at productive@getarth.ai.

See what Claude Code did — every tool call, agent spawn, and workflow phase visualized in a dashboard.

Two telemetry streams, both required for full data:

• Toolkit hook — adds session/prompt/tool/agent/skill spans (installed by sentinel below).
• Claude Code native OTEL — adds cost USD, input/output/cache tokens, and model to those spans (gated by the env var CLAUDE_CODE_ENABLE_TELEMETRY=1).

/otel-setup turns both on for you. Without CLAUDE_CODE_ENABLE_TELEMETRY=1, the dashboard's cost and token columns stay empty — that's the most common "why is my dashboard half-broken?" question.

Prerequisites

• Docker Desktop installed and running on your machine (download here)
• Verify Docker is working: open your terminal and run docker info. If you see version info, you're good. If you see an error, open Docker Desktop first.
• Ports 4319, 3100, 5432 available on localhost (engine, dashboard, postgres). If any of these are in use, stop the conflicting service before continuing.

7a: Install the sentinel bundle (skip if you installed prime)

Inside Claude Code:

/plugin install sentinel@arthaiCopy

This adds the OTEL tracing hook and the /otel-setup skill to your project.

If you already have sentinel installed, update it (or rely on auto-update from Step 5):

/plugin marketplace update arthai
/plugin uninstall sentinel@arthai
/plugin install sentinel@arthai
/reload-pluginsCopy

7b: Restart Claude Code

Close and reopen Claude Code (or start a new session). When the session starts, you'll see this message:

OTEL_SETUP_REQUIRED: Observability is installed but not configured.
Run /otel-setup now.Copy

7c: Run /otel-setup

No toolkit? Use the Arth CLI instead. Everything in Step 7 is the toolkit path. If you're not running the Claude Code toolkit, install the Arth CLI (one line, below) and run arth otel-setup — it stands up the identical stack (db + dashboard on :3100 + engine on :4319) and writes the same global native-OTEL env, no toolkit required. See Installing the Arth CLI just below, then continue to Step 8 / arth cloud-setup. If you later install the toolkit, /otel-setup detects this stack and only adds toolkit attribution.

Installing the Arth CLI (no toolkit)

The Arth CLI ships through the private Arth distribution repo — install is gated by the same GitHub access you already have (the repo invite + your ARTH_GITHUB_TOKEN); no public package. Requires Node.js 22+.

Need a token? ARTH_GITHUB_TOKEN is a GitHub fine-grained PAT with Contents: Read on ArthTech-AI/arthai-marketplace — the same one the orchestrator uses. Create it the way described in the Cloud Orchestrator prerequisites (github.com → Settings → Developer settings → Fine-grained tokens → Resource owner ArthTech-AI, repo arthai-marketplace, Contents: Read-only). Already use the gh CLI and it can read that repo? The installer will use gh auth token automatically — no need to set the variable.

# 1) Make sure your GitHub token (read access to ArthTech-AI/arthai-marketplace) is set:
export ARTH_GITHUB_TOKEN=github_pat_...     # or have the `gh` CLI logged in

# 2) Install the Arth CLI (downloads the self-contained binary onto your PATH).
#    Private repo → use the GitHub contents API with the raw accept header:
curl -fsSL -H "Authorization: Bearer $ARTH_GITHUB_TOKEN" \
  -H "Accept: application/vnd.github.raw" \
  https://api.github.com/repos/ArthTech-AI/arthai-marketplace/contents/cli/install.sh | sh

# 3) Verify it's on your PATH:
arth --helpCopy

Without read access to the repo the download 404s — that's the access gate. The installer puts arth in ~/.local/bin — if arth --help says "command not found", add that to your PATH: export PATH="$HOME/.local/bin:$PATH" (the installer prints this hint too). It also warns (but doesn't block) if you haven't activated a license yet: you only need the Arth license later, for arth cloud-setup → the experimental Cloud Orchestrator. Then:

arth otel-setup     # telemetry stack — no license needed
arth cloud-setup    # Explain this session + the experimental Cloud OrchestratorCopy

Updating the CLI later: re-run the same install one-liner — it overwrites arth with the latest published build and re-verifies the checksum.

Type:

/otel-setupCopy

The skill asks how you want to set up. Pick "Local" (option 2).

The skill then does everything for you automatically:

1. Checks Docker is running on your machine
2. Creates a configuration file at ~/.arthai/docker-compose.yml
3. Downloads the Arth Intelligence Docker image (first time takes 1-2 minutes)
4. Starts the engine on :4319 (receives traces) + dashboard on :3100 (shows traces) + database (stores traces) + Watchtower (auto-updates the engine image daily)
5. Waits until everything is healthy
6. Writes environment variables — including CLAUDE_CODE_ENABLE_TELEMETRY=1 — to your global ~/.claude/settings.json by default (so every project on this machine emits telemetry; nothing is committed to your repos). If you pick the "this project only" scope instead, they go to that repo's .claude/settings.local.json.
7. Creates a marker file so it doesn't ask you again

It asks two quick questions along the way — env-var scope (global vs this-project-only) and whether to keep session auto-tagging on — then runs unattended until done.

7d: Restart Claude Code (mandatory)

Close and reopen Claude Code so it picks up the new env block from ~/.claude/settings.json (or the repo's .claude/settings.local.json if you chose project-only scope). Without this restart, the env vars aren't loaded and traces won't flow.

7e: Verify it's working

You've just restarted Claude Code. The dashboard exists but is empty — there's no data yet because you haven't done anything yet. Walk through these in order:

1. Open the dashboard in your browser. Go to http://localhost:3100. You should see the Arth Intelligence Hub — a project/session list with an Experiments page in the sidebar. The Hub will probably be empty at this point — that's expected, you haven't run anything yet.

If the page doesn't load at all, the Docker stack may not be up. Run:

   docker psCopy

You should see three containers — arthai-intelligence, arthai-db, arthai-watchtower. If any are missing:

   docker compose -f ~/.arthai/docker-compose.yml up -dCopy

1. Generate some activity in Claude Code. Switch back to Claude Code and run any prompt — even something trivial: Or: The toolkit's OTEL hook emits trace spans for every prompt, tool call, agent spawn, and stop event. Native OTEL emits cost and token data alongside.

   what's in package.json?Copy

   /onboardCopy

1. Refresh the dashboard. Your session should appear in the Sessions list with a recent timestamp. If nothing appears after ~10 seconds, the engine may not be receiving traces. Check engine health: Expect a JSON response containing "ok":true. If it fails, check logs:

   curl -s http://localhost:4319/api/health | jq .Copy

   docker logs arthai-intelligence | tail -50Copy

1. Click into your session. You should see a waterfall of spans — your prompt, the tool calls Claude Code made, any agent spawns, etc. Each span shows duration and metadata.

1. Confirm cost columns are populated. Look at the cost / token columns in the trace.

• If they show values (e.g. $0.0023, 1,847 tokens) → native OTEL is flowing. You're done.
• If they show — or are empty → only the toolkit hook is on. Native OTEL needs CLAUDE_CODE_ENABLE_TELEMETRY=1. Verify: If missing, re-run /otel-setup, pick Local again, then restart Claude Code.

    grep CLAUDE_CODE_ENABLE_TELEMETRY ~/.claude/settings.json
    # or, if you chose project-only scope: grep CLAUDE_CODE_ENABLE_TELEMETRY .claude/settings.local.json
    # should print: "CLAUDE_CODE_ENABLE_TELEMETRY": "1"Copy

If all 5 steps work — observability is working end-to-end. Future Claude Code sessions automatically send traces to http://localhost:3100. You don't need to do anything else.

7f: Capture a baseline — observer-only mode (optional)

Sometimes you want to know: what does Claude Code do on its own, vs. what changes when the toolkit is active? Maybe you're evaluating whether to keep the toolkit on for a particular workflow, or you want to debug a behavior and need to isolate "is this the toolkit or is this Claude itself?"

Observer-only mode is for that. It keeps the OTEL hook emitting telemetry (so you still see the run in the dashboard), but suppresses every toolkit-specific side effect:

export OTEL_OBSERVE_ONLY=trueCopy

Then launch Claude Code as you normally would. That session's spans land in the dashboard exactly like a regular run, but:

• No skill.current.json written (the file that tracks active slash commands for span attribution)
• No agent.<id>.json written (the file that brackets subagent spans)
• No "run /otel-setup" nag if observability isn't configured yet
• Every span carries an extra resource attribute: arth.observe_only=true

To clear it, unset OTEL_OBSERVE_ONLY (or just open a new shell). It only applies to sessions started while the env var is set.

Typical A/B workflow:

1. Run a normal Claude Code session — do something representative (e.g., ask /onboard to brief you, then ask a follow-up).
2. Open a new terminal, export OTEL_OBSERVE_ONLY=true, and launch Claude Code again. Run the same prompts.
3. In the dashboard, find the two sessions side-by-side. The toolkit-on run has skill attribution (skill.name = "onboard" on the tool spans); the observer run does not. Compare the trace shapes, durations, and span counts.

That diff is the toolkit's contribution to your workflow.

Precedence — which env wins:

Filtering observer runs in the dashboard UI ships in a future release. Until then, the arth.observe_only attribute is carried on every span of an observer run — the runs appear in the dashboard alongside normal ones.

7f.1: Compare baseline vs toolkit in the arth dashboard

Once you've captured a baseline run AND a regular toolkit run, the arth dashboard's /experiments page renders them side-by-side across cost, tokens, calls, cache hit rate, lines edited, and active time.

Auto-tagging (default ON for both modes):

Every session you run automatically gets an arth.experiment label so it shows up in /experiments dropdowns without you having to set anything before each launch. The label format makes baseline vs toolkit easy to scan:

Example after running the same task twice:

auto-baseline-main-debug-login-failure-1715890123
auto-toolkit-main-1715891456Copy

Pick one as left, the other as right, click Compare.

Quick walkthrough — zero-config path:

1. Run baseline first (no env vars, no aliases). Just claude in your project.
2. Run toolkit second (still no env vars). Just claude again — the toolkit auto-installs the hook.
3. Open the dashboard at http://localhost:3100/experiments. Both runs are already in the dropdowns.
4. Pick left = baseline, right = toolkit, click Compare.

Custom labels (override auto-tag):

If you want a specific human-readable label instead of the auto one, set arth.experiment before launching — your value wins:

export OTEL_RESOURCE_ATTRIBUTES="$OTEL_RESOURCE_ATTRIBUTES,arth.experiment=prepme-credit-bug-baseline"
claudeCopy

Turn auto-tagging OFF:

Set ARTH_AUTO_EXPERIMENT_DISABLED=1 — same env var honored by both modes:

• ~/.arthai/docker-compose.yml environment: block → disables the engine watcher's auto-tag (no-toolkit / orphaned-toolkit sessions)
• <project>/.claude/settings.local.json env block → disables the toolkit hook's auto-tag (toolkit sessions)

/otel-setup asks you about this at install time — you can flip it then or at any point later.

Mid-session annotations — type /marker "spike here" inside any session. An amber ◆ glyph appears on the dashboard's DAG timeline within ~5s. From the dashboard, you can also click Drop marker on any session detail page. Export filtered slices — /arth logs export --since 1h from inside Claude Code, OR use the dashboard sidebar's "Download diagnostic bundle". Filter by experiment, marker, session ID, and time range — all AND-compose.

The Arth Intelligence guide has the condensed version of this comparison flow.

7g: What survives a reboot

After you reboot your Mac (or restart Docker Desktop), here's what comes back automatically and what doesn't:

Quick verify after a reboot:

docker ps --filter 'name=arthai'
# Should show 3 running containers: arthai-intelligence, arthai-db, arthai-watchtowerCopy

If any are missing, start them:

docker compose -f ~/.arthai/docker-compose.yml up -dCopy

Migration for older installs (containers showing RestartPolicy: no):

If docker inspect shows your containers have RestartPolicy: no, run this one-liner — no data loss, no re-setup:

docker update --restart unless-stopped arthai-db arthai-intelligenceCopy

Or re-run /otel-setup and pick Local — the new compose template will overwrite ~/.arthai/docker-compose.yml with the right policy.

Opting out of auto-restart:

If you'd rather start Arth Intelligence manually each session (e.g., to save resources when not coding):

docker update --restart no arthai-db arthai-intelligence arthai-watchtowerCopy

You'll need to docker compose -f ~/.arthai/docker-compose.yml up -d whenever you want the dashboard back.

7h: Updating Arth Intelligence

There are three things that can update independently. Each has its own update path. None of them touch your trace data — your sessions, scores, and patterns live in the arthai_data Docker volume and are preserved across all updates.

The container image — two ways

Automatic (default). A watchtower sidecar shipped in the compose template checks once a day, pulls the latest arthai/intelligence image, and restarts only that container. You don't need to do anything. To verify it's running:

docker ps --filter name=arthai-watchtowerCopy

Manual — force an update right now. Run the hosted update script:

curl -fsSL https://arthtech-ai.github.io/__ARTH_MARKETPLACE__/scripts/update.sh | shCopy

Or paste the two commands directly if you'd rather not pipe to shell:

docker compose -f ~/.arthai/docker-compose.yml pull
docker compose -f ~/.arthai/docker-compose.yml up -dCopy

Both do the same thing — pull the latest image and recreate the container against it. The named volume arthai_data is left untouched.

To opt out of auto-updates:

docker stop arthai-watchtower
docker rm arthai-watchtowerCopy

You'll then need to update manually using the script above whenever you want a new version.

The skill — when we ship a new /otel-setup

/plugin marketplace update arthai
/plugin uninstall sentinel@arthai
/plugin install sentinel@arthai
/reload-pluginsCopy

If that doesn't pick up the change, fall back to the marketplace remove + re-add flow shown in the FAQ.

The compose file — only matters if the template changes

If a sentinel release changes the compose template (e.g. adds a new service), you'll need to re-run /otel-setup to regenerate ~/.arthai/docker-compose.yml with the new content. Re-running the skill is safe — it overwrites the compose file but never touches the arthai_data volume.

The one thing that destroys data

docker compose -f ~/.arthai/docker-compose.yml down -v   # ← DON'T DO THISCopy

The -v (--volumes) flag drops the arthai_data volume and erases every session, score, and pattern. Plain docker compose down (without -v) stops the containers but keeps the data — that's safe and reversible. Only use down -v if you intentionally want to wipe everything and start fresh.

What you see in the dashboard

• Session waterfall — colored swimlanes showing agents, tools, tasks, permissions
• Agent cost tiers — which agents ran at Opus (60x), Sonnet (10x), Haiku (1x)
• Tool call duration — how long each tool call took
• Workflow phases — spec generation, scope debate, implementation, QA
• Session summaries — duration, agent count, task count, failures

Troubleshooting

7i: Enable the dashboard's AI features (optional)

/otel-setup (above) is telemetry-only. On top of it there are two separate optional features — don't conflate them:

Not sure which keys you need? See Configuration → Keys at a glance for a one-table summary. Short version: telemetry needs none, Explain on a local model (Ollama / LM Studio + qwen) needs none, a cloud Explain model needs that provider's key, and only the experimental orchestrator needs a Claude key + GitHub token + license.

A. "Explain this session" — a grounded AI summary. NOT experimental. You can turn this on without the experimental orchestrator. It's offered at the end of /otel-setup (or arth otel-setup), and also by /cloud-setup. Pick any provider — including free local models:

New user: just answer "yes" when /otel-setup offers Explain and pick a provider. Existing user (set up before this): re-run /otel-setup (or /cloud-setup) and opt into Explain — your key is added to ~/.arthai/.env and survives image updates. Local-model step-by-step: Configuration → Local models.

B. Cloud Orchestrator — experimental, Claude-only. Point Arth at a Git repo and watch it calibrate or plan a feature live. Off until you opt in via /cloud-setup (toolkit) or arth cloud-setup (CLI):

/cloud-setup        # in Claude Code (toolkit)
arth cloud-setup    # from a terminal (Arth CLI — no toolkit needed)Copy

The sandbox runs Claude only (for now), so you'll need an ANTHROPIC_API_KEY even if you set Explain to a non-Claude provider (both keys are kept). Plus your license (auto-read from ~/.arthai/license if you ran npx arthai-activate) and a GitHub fine-grained token with read access to ArthTech-AI/arthai-marketplace. See the Cloud Orchestrator guide for how to create the token + the full walkthrough.

Step 8: Calibrate your project

On first use in a project, run:

/calibrateCopy

This scans your codebase and configures the toolkit to match your project's patterns, conventions, and tech stack. It also builds a knowledge graph — a ranked index of your project's conventions, domain rules, and patterns that workflows like /fix query automatically to get the most relevant context for each task. The graph auto-rebuilds whenever your knowledge base changes.

Want it cheaper? Calibrate's sub-agents are already Haiku/Sonnet — the only Opus cost is the Claude Code session driving it (your "model" setting, not the toolkit). Run /model sonnet before /calibrate for a no-Opus pass. Details: /calibrate → Cost & running it cheaply.

Step 9: Start a new Claude Code session

Restart your Claude Code session so the knowledge graph gets built and the OTEL env block from Step 7 is picked up. Then:

/onboard                    # prioritized briefing on what to work on
/planning my-feature        # start building with the toolkitCopy

You're ready.

Recommended first session

After installing and calibrating:

/onboard                    # get a briefing on your project
/planning my-first-feature  # try the planning workflow
/implement my-first-feature # spawn the team that builds it
/qa                         # commit-mode QA on the diff
/pr                         # create the PRCopy

If you're not building something new, two good explorations:

/tech-debt                  # survey, prioritize, and propose plans for tech debt
/perf <scope>               # cross-functional performance passCopy

Common skills — cheat sheet

The full list of every skill in your installed bundles is at skills-reference.md. The most common ones grouped by what you're doing:

Bundle-specific skills (consulting, design, etc.) live in their respective bundles — install the bundle to surface them. See the plugin catalog.

Using Cowork Dispatch (tweet → pipeline)

Partner installs only. This feature requires access to the claude-agents source repo, which standard plugin customers don't have. Skip this section unless Arth AI has given you source access.

Cowork is Anthropic's mobile companion app for Claude. The prime bundle includes a Cowork Dispatch skill: paste a tweet URL in Cowork and it automatically queues /monitor-tweet on your desktop Claude Code.

Additional requirement: the Cowork skill dispatches to ~/.claude-agents on your Mac — a source-repo clone. You need both:

# 1. Plugin install (above) — surfaces the skill in Cowork
# 2. Clone the toolkit to ~/.claude-agents — provides /monitor-tweet on desktop
git clone git@github.com:ArthTech-AI/claude-agents.git ~/.claude-agents
~/.claude-agents/install.sh --key ARTH-XXXX-XXXX-XXXX-XXXX ~/.claude-agentsCopy

Without the clone, the Cowork skill fires but the desktop pipeline has no /monitor-tweet to run.

Knowledge graph

When you run /calibrate, the toolkit builds a knowledge graph from your project's knowledge base (.claude/knowledge/). This is a ranked index of your conventions, domain rules, patterns, and vocabulary that agents query automatically.

How it works:

1. /calibrate scans your codebase and populates .claude/knowledge/shared/ with conventions, domain rules, patterns, and vocabulary
2. The knowledge graph indexes these files into a fast-lookup graph (.claude/knowledge/graph/)
3. When any skill runs (/fix, /planning, /implement, /qa, etc.), it queries the graph to pull in only the most relevant context — instead of loading every knowledge file in full
4. The graph auto-rebuilds whenever your knowledge base changes

What this means for you:

• Agents make better decisions because they have ranked, relevant project context
• Fixes match your coding conventions automatically
• QA checks understand your domain rules
• No action needed from you — it runs behind the scenes after /calibrate

Next steps

• Tutorial: ship your first PR — the 10-minute golden path
• Tutorial: calibrate a project · plan and implement a feature
• What is arthai? — positioning, who it's for, how the pieces fit
• Arth Intelligence — the observability dashboard explained
• Configuration — customize the toolkit for your workflow
• Plugin catalog — see all available bundles
• FAQ — common questions and answers

Uninstall

Fully remove the arthai toolkit (and, optionally, Arth Intelligence) and get back to a clean Claude Code with no hook errors. Works for the plugin install path (@arthai). Steps run in Claude Code, then your terminal.

Step 1 — Remove the plugins (in Claude Code)

Run for each bundle you installed (prime, or forge/scalpel/sentinel/…):

/plugin uninstall prime@arthai        # repeat per bundle
/plugin marketplace remove arthaiCopy

This removes the skills, agents, and hooks that live inside the plugin directory.

Step 2 — Fully quit and reopen Claude Code

This is the step that prevents hook errors. It drops the plugin's hooks from the running session. Don't just /clear — quit the app/CLI completely, do Step 3 while it's closed, then reopen.

Step 3 — Remove the leftovers (in your terminal)

Plugin uninstall does not touch your project's CLAUDE.md, the toolkit's per-project state files, or global config. Run from your project root (macOS: use sed -i '' instead of sed -i):

# Global: plugin cache
rm -rf ~/.claude/plugins/cache/*arthai*

# Keep your Arth license (~/.arthai/license) so you don't need a new key to return.
# Remove only the observability config from ~/.arthai (license stays):
rm -f ~/.arthai/docker-compose.yml ~/.arthai/docker-compose.override.yml
rm -f ~/.arthai/.env ~/.arthai/otel-configured

# Per project: remove the managed blocks the toolkit injected
sed -i '/>>> claude-agents toolkit/,/<<< claude-agents toolkit/d' CLAUDE.md
sed -i '/>>> claude-agents managed/,/<<< claude-agents managed/d' .gitignore

# Per project: remove toolkit STATE files (config/routing/workflow caches) —
# NOT your generated content (preserved below)
rm -f .claude/.claude-agents.conf .claude/registry.json .claude/.triage-full-emitted \
      .claude/verification-pending .claude/.workflow-state.json .claude/.autopilot-state.json \
      .claude/.skill-usage.json .claude/.project-state-cache.json .claude/.toolkit-setup-done \
      .claude/.toolkit-last-seen-sha .claude/.cc-version .claude/.license-validated \
      .claude/.precheck-passed .claude/.escalation-state.json .claude/.fix-scope-lock.json \
      .claude/.context-block.cache .claude/.arth-otel.env
rm -rf .claude/.goalsCopy

If .claude/settings.json still references toolkit hooks afterward (only if the dev/symlink installer was ever used), delete the hooks entries whose command path contains claude-agents, arthai, or .claude/hooks/, then restart.

Optional — remove the license key too

The steps above keep your license at ~/.arthai/license so you can reinstall later without requesting a new key. Only remove it if you're done with arthai for good (you'd need a new key to come back):

rm -rf ~/.arthai      # ⚠ also deletes your license keyCopy

Step 4 — Remove Arth Intelligence (only if you enabled observability)

Stop the local Docker stack (your trace data is in the arthai_data volume — plain down keeps it; down -v erases it):

docker compose -f ~/.arthai/docker-compose.yml down      # stop containers, keep data
# docker compose -f ~/.arthai/docker-compose.yml down -v  # ⚠ also erases all trace dataCopy

Network arthai_default — Resource is still in use? Harmless. The arthai containers are removed; the network just isn't deleted because another of your containers is still attached to it. /otel-setup reuses the same network on the next start — nothing to fix. (Don't force-disconnect your own containers from it.)

Then turn off the toolkit's telemetry env. By default /otel-setup wrote the six OTEL_* / CLAUDE_CODE_ENABLE_TELEMETRY keys to your global ~/.claude/settings.json (or a repo's .claude/settings.local.json if you chose project scope). For a complete removal, delete just those six keys — the Arth Intelligence guide lists them and shows how to remove only those (your other settings stay). Prefer not to edit a settings file at all? export OTEL_DISABLED=true turns telemetry off without changing anything. Either way, also clear the cached endpoint file:

rm -f .claude/.arth-otel.envCopy

Upgrading, not leaving? You don't need to remove the env block at all — keep it, reinstall, and run /otel-setup → Reconfigure → Local. It refreshes the six keys itself (merging without overwriting your other settings), pulls the latest image, and recreates the stack — a full OTEL install with nothing hand-edited. Your trace history is untouched either way (it lives in the arthai_data volume).

Step 4b — Remove Cloud Orchestrator leftovers

If you enabled the AI features — the Explain provider key/host (incl. a local OLLAMA_HOST / LMSTUDIO_HOST), set via /otel-setup or /cloud-setup, and any orchestrator secrets/flags — they live in ~/.arthai/.env + ~/.arthai/docker-compose.override.yml, both already removed by rm -rf ~/.arthai in Step 3. The Cloud Orchestrator also launches disposable sandbox containers and pulls a sandbox image — neither is managed by the compose file above, so down doesn't remove them. Clean up any leftovers:

# Remove any orphaned/stuck per-run sandbox containers
docker ps -aq --filter "name=arth-cloud-" | xargs -r docker rm -f

# Optional: drop the sandbox image too
docker rmi arthai/cloud-sandbox:latest 2>/dev/null || trueCopy

(Findings data lives in the arthai_data volume, so down -v above already erases it — no separate step needed.)

Step 5 — Reopen Claude Code and verify

/help        → toolkit slash commands (/pr, /qa, /onboard, /skills…) are gone
/plugin      → arthai is no longer listedCopy

No hook errors on startup means it's clean — because you quit fully in Step 2, Claude Code rebuilds the hook set from scratch with no toolkit entries.

What's preserved on purpose

Uninstall never deletes content the toolkit generated for you — it's yours: .claude/knowledge/, .claude/plans/, .claude/specs/, .claude/qa-knowledge/, .claude/wikis/, .claude/project-profile.md. To remove that too:

rm -rf .claude/knowledge .claude/plans .claude/specs .claude/qa-knowledge \
       .claude/wikis .claude/project-profile.mdCopy

Reinstall

To come back later: Getting Started — /plugin marketplace add ArthTech-AI/arthai-marketplace then /plugin install prime@arthai.

For a clean upgrade (full reinstall): you don't have to edit any settings file. Uninstall the plugins (Steps 1–2), stop the stack with docker compose down (Step 4 — run it before rm -rf ~/.arthai, since deleting the folder first removes the compose file you need), reinstall, then run /otel-setup → Reconfigure → Local for a full, idempotent OTEL install. Everything except the per-project .claude/ cleanup is machine-wide — plugins, the license, the Docker stack, and the global OTEL env apply to every repo, so you reinstall once; only the .claude/ cleanup and /calibrate are per project.

Related

• Getting Started — install
• Arth Intelligence — full observability teardown
• FAQ — common install/uninstall questions

Arth Intelligence — Observability for Claude Code

⚠️ Experimental — limited preview. Observability is in active development. Expect rough edges, breaking changes between releases, and gaps in coverage. Feedback welcome at productive@getarth.ai.

Arth Intelligence is a local dashboard that shows you what Claude Code actually did — every session, prompt, tool call, agent spawn, skill invocation, and dollar spent. It runs entirely on your machine as a Docker container. Nothing leaves your laptop.

This page covers the default experience: Observability only. Out of the box the dashboard is a single observability surface (Hub / Sessions / DAG / Story / Experiments / Cost) — exactly what's described below. There is an optional, experimental Cloud Orchestrator add-on (point Arth at a repo to calibrate or plan it live, plus a visual Knowledge view) that is off by default and completely hidden unless you opt in. If you turn it on, the left nav regroups into three lenses and "Hub" is renamed "Observability" — see Cloud Orchestrator. Not interested? Do nothing; everything on this page is all you'll see.

Why you'd want it

• See the work. A session is no longer a black box — click into a waterfall of spans showing every tool call and agent spawn with durations.
• See the cost. Per-call cost in USD, input/output/cache tokens, and which model tier each agent ran at (Opus 60x / Sonnet 10x / Haiku 1x).
• Prove the toolkit's value. Run the same task with and without the toolkit and compare cost, tokens, and outcomes side-by-side on the /experiments page.
• Debug workflows. When a skill misbehaves, the trace shows exactly which phase, which agent, and which tool call went wrong.

How it works — two telemetry streams

Both streams flow into the same local engine. If native OTEL is off, traces still flow but the dashboard's cost and token columns stay empty — that's the most common "why is my dashboard half-broken?" question.

Setup

Prerequisites: Docker Desktop running; ports 4319 (engine), 3100 (dashboard) free; the sentinel plugin installed (or prime, which includes it). Optional: an LLM API key (Anthropic / OpenAI / Gemini / Bedrock) or a free local Ollama / LM Studio (LM Studio auto-detects the loaded model, e.g. qwen) — only if you want the AI "Explain this session" summaries (/otel-setup will offer to set this up; skip it and everything else works).

/plugin install sentinel@arthai    # skip if you installed prime
/otel-setup                                # pick "Local"Copy

/otel-setup does everything: verifies Docker, writes ~/.arthai/docker-compose.yml, starts the stack (engine + dashboard + postgres + Watchtower auto-updater), and writes the env vars to your global ~/.claude/settings.json (so every project on this machine emits telemetry — nothing is committed to your repos):

CLAUDE_CODE_ENABLE_TELEMETRY=1
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4319
OTEL_EXPORTER_OTLP_PROTOCOL=http/json
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_TRACES_EXPORTER=otlpCopy

Then restart Claude Code — without the restart, the env vars aren't loaded and traces won't flow.

Verify it's working

1. Open http://localhost:3100. You should see the dashboard's Hub — your projects and sessions (empty until you run something). If it doesn't load: docker ps should show arthai-intelligence, arthai-db, and arthai-watchtower; if missing, docker compose -f ~/.arthai/docker-compose.yml up -d.
2. Generate activity. In Claude Code, run any prompt — even "what's in package.json?".
3. Refresh the dashboard. Your session appears in the Sessions list. If nothing shows after ~10s: curl -s http://localhost:4319/api/health | jq .
4. Click into the session. You see the span waterfall — prompt, tool calls, agent spawns, durations.
5. Check the cost columns. Values like $0.0023 mean native OTEL is flowing — you're done. Empty columns mean CLAUDE_CODE_ENABLE_TELEMETRY=1 isn't loaded: grep CLAUDE_CODE_ENABLE_TELEMETRY ~/.claude/settings.json, re-run /otel-setup if missing, restart Claude Code.

Connecting your other projects

By default /otel-setup writes the OTEL env block to your global ~/.claude/settings.json, which Claude Code reads for every folder on this machine — so all your projects (and any you create later) report to the same localhost:4319 engine and appear in the same dashboard automatically. There's nothing to repeat per repo.

Check it's set:

grep CLAUDE_CODE_ENABLE_TELEMETRY ~/.claude/settings.jsonCopy

(If you deliberately chose the This project only scope during /otel-setup, the block lives in that repo's .claude/settings.local.json instead and only that repo is connected.)

Verify a specific repo end-to-end: start a Claude Code session in it, run any prompt, then look for a new session in the dashboard — every session carries the project name and path (and an auto-experiment label with the git branch), so each repo is identifiable in the Sessions list. No new session after ~10s means that repo's env block is missing or the session wasn't restarted after setup.

What the dashboard shows

Hub — every project and session in one tree: segments, span counts, duration, cost, and last activity, updating live while a session runs. (With the Cloud Orchestrator add-on enabled, this lens is renamed Observability and joined by Orchestrator and Knowledge lenses — otherwise it stays "Hub".)

Session detail — click any session for four views (Story / DAG / Spans / Trace): the narrative of what happened, a DAG timeline of agents and tools, the raw span list, and the trace waterfall. Each session also shows:

• Insights strip — automatic good / watch / concern findings (e.g. elevated error rates)
• Cost breakdown — three axes: by model, by skill, and by owner (toolkit vs Claude Code vs 3rd-party plugins vs direct prompting), per model tier
• Explain this session (optional, not experimental) — a grounded, plain-language AI summary of what happened. It calls an LLM directly (separate, API-billed — not your Claude Code subscription; ~$0.001–0.002/session on a small/flash model, or free with local Ollama / LM Studio) and is opt-in: enable it from /otel-setup (or arth otel-setup) — it's offered inline — or with /cloud-setup. Any provider works (Anthropic / OpenAI / Gemini / Bedrock / Ollama / LM Studio — the last auto-detects the loaded model, e.g. qwen). With no key configured, the dashboard shows a small "needs an LLM key" prompt where the summary would go (it doesn't silently disappear). To turn it on — including on an existing install that predates this feature — re-run /otel-setup (or /cloud-setup) and provide a key; it's saved to ~/.arthai/.env and survives image updates (pulls/Watchtower never remove it). See Configuration → Explain this session.
• Workflow phases — spec generation, scope debate, implementation, QA checkpoints
• Markers — drop /marker "spike here" mid-session; an amber ◆ appears on the DAG timeline

Experiments — pick any two experiment labels and compare them side-by-side on six metrics (cost, tokens, API calls, cache hit rate, lines edited, active time) plus workflow attribution. Two caveats: cost/token/cache metrics need native OTEL enabled (sessions without it show 0), and lines-edited only populates for toolkit-instrumented sessions.

Project view — a Today summary with a velocity score (composite of outcome rate, toolkit coverage, and cost efficiency) and data-backed coaching insights (e.g. "start with /planning — your last 4 sessions averaged 3 pivots without a plan").

Diagnostic bundle — one click in the sidebar (or /arth logs export) zips engine logs and a redacted span slice for support.

Compare: baseline vs. toolkit

Want to know what the toolkit actually changes? Every session is auto-tagged for the /experiments page — no setup:

1. Run a session without the toolkit (claude in a project with no plugin) → tagged auto-baseline-<branch>-<prompt-slug>-<unix>.
2. Run a session with the toolkit → tagged auto-toolkit-<branch>-<unix>.
3. Open http://localhost:3100/experiments, pick one on each side, click Compare. Cost, tokens, calls, cache hit rate, lines edited, and active time fill in side-by-side.

For observer-only mode (OTEL_OBSERVE_ONLY=true — telemetry on, toolkit side effects off), custom experiment labels, and the full A/B walkthrough, see Getting Started Step 7.

Privacy — what leaves your machine

Nothing. The engine, dashboard, and database all run in local Docker containers. Trace data lives in the arthai_data Docker volume on your machine. The env vars live in a git-ignored file. The only outbound traffic is Watchtower pulling image updates from Docker Hub.

Operations

Details on reboot durability and the three update layers: Getting Started 7g–7h.

Am I on the latest version?

Watchtower pulls the latest arthai/intelligence image daily, so you're normally current automatically. To check manually, compare the image your container is running against Docker Hub:

docker compose -f ~/.arthai/docker-compose.yml images arthai-intelligenceCopy

Compare the image ID against the :latest tag on Docker Hub. If they differ, run Update now above (or wait for Watchtower).

Uninstall Arth Intelligence

Removing observability doesn't touch the toolkit — skills and agents keep working without it.

# 1. Stop and remove the containers (keep the trace data)
docker compose -f ~/.arthai/docker-compose.yml down

#    …or wipe the trace data too (permanent):
docker compose -f ~/.arthai/docker-compose.yml down -v

# 2. Remove the config and the "already configured" marker
rm -f ~/.arthai/docker-compose.yml ~/.arthai/otel-configuredCopy

1. Remove the OTEL env block (the six OTEL_* / CLAUDE_CODE_ENABLE_TELEMETRY keys) from ~/.claude/settings.json — or from a project's .claude/settings.local.json if you used project-only scope there — and delete any cached endpoint file: rm -f .claude/.arth-otel.env (a stale copy can silently misroute telemetry if you ever reinstall). Quick alternative while deciding: export OTEL_DISABLED=true turns everything off without removing anything.

1. Restart Claude Code.

To uninstall the whole toolkit instead, see the README Uninstall section.

Troubleshooting

More Q&A: FAQ — Observability.

Related

• Getting Started — Step 7 — the full install walkthrough (7a–7h)
• What is arthai? — how observability fits the toolkit
• Configuration — OTEL env var reference

Configuration

Auto-configuration

The fastest way to configure is:

/calibrateCopy

This scans your codebase and sets up agents, skills, and hooks to match your project's patterns. It's safe to run multiple times.

Manual configuration

Project-specific agents

Add custom agents as .md files in your project's .claude/agents/ directory. These run alongside the plugin agents.

Project-specific skills

Add custom skills as directories in .claude/skills/. Each skill needs a SKILL.md file with frontmatter.

Overriding plugin defaults

Project-local files take precedence over plugin-provided ones of the same name:

1. Create .claude/agents/<name>.md (or .claude/skills/<name>/SKILL.md) in your project
2. Give it the same name: as the plugin agent/skill you want to replace

Your override is a regular project file — future plugin updates never touch it.

Bundle selection guide

Multiple bundles

You can install multiple bundles. They compose without conflicts:

/plugin install forge@arthai
/plugin install sentinel@arthai
/plugin install prism@arthaiCopy

Observability (OTEL)

The sentinel bundle includes the otel-telemetry hook and /otel-setup skill for tracing every Claude Code session.

Setup

/otel-setupCopy

The skill prompts for your preferred setup. Pick "Local" — it runs everything on your machine.

Prerequisite: Docker Desktop installed and running.

The skill pulls arthai/intelligence from Docker Hub, starts the engine + dashboard + Postgres, and configures everything automatically.

The skill writes these env vars to .claude/settings.local.json (project-local, git-ignored) by default, or to your shell profile if you pick the global scope:

What gets traced

The hook captures 22 Claude Code event types:

• Session lifecycle: start, end, stop failure
• User prompts: with skill detection (freeform vs /skill-name)
• Agent lifecycle: start/stop with cost tier (opus-60x, sonnet-10x, haiku-1x) and duration
• Tool calls: pre/post with input summary, output summary, and wall-clock duration
• Tasks: created/completed with subject
• Errors: tool failures, permission denials with error messages
• Context: compaction events, instructions loaded, cwd changes
• Environment: worktree create/remove, notifications, teammate idle

Critical spans (session.end, agent.stop) are sent synchronously with a 1s timeout for reliable delivery. All other spans are fire-and-forget (<10ms overhead).

Auto-trigger

If the hook is installed but OTEL is not configured, it automatically prompts you to run /otel-setup on your next session start. This only fires once — after setup, a marker file (~/.arthai/otel-configured) prevents re-prompting.

Disabling

export OTEL_DISABLED=trueCopy

"Explain this session" — optional LLM key

The Intelligence dashboard's grounded "Explain this session" summary calls an LLM directly (NOT your Claude Code subscription — separate, API-billed). It's optional: with no key the dashboard shows a "needs an LLM key" prompt where the summary would go (it doesn't silently vanish).

Where you configure it (it's NOT experimental): you can enable Explain in either setup command — you do not need to turn on the experimental Cloud Orchestrator:

• With the toolkit: /otel-setup offers it at the end, or run /cloud-setup (Step 1).
• Without the toolkit (CLI): arth otel-setup offers it at the end, or run arth cloud-setup. (First install the Arth CLI — gated by your GitHub repo access, no public package.)

Either way your choice lands in ~/.arthai/.env and survives image updates (pulls and Watchtower never remove it). Use any one provider — a small / flash-tier model is recommended (it only summarizes facts):

Override the model with ARTH_EXPLAIN_MODEL and force a provider with ARTH_EXPLAIN_PROVIDER (accepts lmstudio/ollama). Cost: ~$0.001–0.002 per session on the cloud models (cached per session) → a few dollars/month even at heavy use, or $0 with local Ollama / LM Studio. Don't use a frontier model here — flash/mini tier is the right size.

Keys at a glance — which do you actually need?

Most of the dashboard needs no key. What you need depends on the two opt-in AI features — and a fully local, zero-key setup is a first-class path:

The local zero-key path (Explain via Ollama / LM Studio, orchestrator off) is the cheapest and most private setup — no provider account, no API bill. The only access you need is the same the toolkit already required: your Arth license (getting started) and repo access to ArthTech-AI/arthai-marketplace. Set it up in /otel-setup (inline) or /cloud-setup, then decline the orchestrator when asked.

Local models step-by-step (Ollama or LM Studio — free)

Both run a local server that the dashboard reaches over the OpenAI-compatible API. The dashboard runs inside Docker, so you must point it at host.docker.internal, not localhost.

LM Studio + qwen (or any model):

1. In LM Studio, download/load the model you want (e.g. a Qwen3 model).
2. Open the Developer / Local Server tab → Start Server → enable "Serve on Local Network" (so the Docker container can reach it). Default port is 1234.
3. Set the env var (or just pick "LM Studio" in /otel-setup / /cloud-setup): The loaded model is auto-detected via /v1/models — you don't need to type its id. To pin a specific one: echo 'ARTH_EXPLAIN_MODEL=<id from /v1/models>' >> ~/.arthai/.env.

   echo 'LMSTUDIO_HOST=http://host.docker.internal:1234' >> ~/.arthai/.envCopy

4. Recreate the dashboard: (Add -f ~/.arthai/docker-compose.override.yml too if you've enabled the orchestrator.)

   docker compose -f ~/.arthai/docker-compose.yml up -dCopy

Ollama:

1. ollama pull llama3.1 (or your model).
2. echo 'OLLAMA_HOST=http://host.docker.internal:11434' >> ~/.arthai/.env
3. Recreate the dashboard (same command as above).

Linux note: if host.docker.internal doesn't resolve, the container needs --add-host=host.docker.internal:host-gateway (Docker Desktop on macOS/Windows adds it automatically), or use the host's LAN IP.

Note — the Cloud Orchestrator is Claude-only (for now). Explain can use any provider above, but the experimental orchestrator's sandbox runs Claude and needs its own ANTHROPIC_API_KEY. So if you set Explain to a non-Claude provider and turn on the orchestrator, you'll be asked for a Claude key as well — both are kept in ~/.arthai/.env.

Updating plugins

Enable auto-updates once: run /plugin, open the Marketplaces tab, select arthai, choose Enable auto-update. Manual update:

/plugin marketplace update arthai
/plugin uninstall <your-bundle>@arthai   # then reinstall, e.g. prime
/plugin install <your-bundle>@arthai
/reload-pluginsCopy

After an update that adds a brand-new command, fully quit and reopen Claude Code. /reload-plugins refreshes existing commands but a running session won't surface a newly added one (e.g. /cloud-setup) until a full restart rebuilds the command set. If an update still doesn't take, use the full reset flow in the FAQ.

Context budget

The toolkit injects guidance into your session — a routing table that picks the right agent/skill for each request, plus a one-line session-start status. Unlike toolkits that load every persona on every message, this one is deliberately lean: the full routing table is injected once per session, then each later turn gets only a compact reminder.

Measured on a reference session:

These numbers are not hand-typed — run scripts/token-budget.sh (or --json) in the source repo for the live figure, which the script re-measures by actually running the hooks. For comparison, framework context bloat is the most-cited complaint about competing toolkits; keeping steady-state cost near ~30 tokens/turn is a deliberate design choice.

Quality Assurance Guide

The arthai QA framework uses a four-layer test strategy with 9 specialized agents.

Four-Layer Test Strategy

Every QA run uses four complementary layers:

1. Baseline Tests — existing test suites (regression anchor, same every run)
2. Generated Scenarios — fresh every run, thinks like real users based on the diff
3. Property-Based Tests — infer invariants from code changes, test with random/edge-case inputs
4. Coverage Audit — reviews if existing tests still match the codebase

Modes

QA Agents

Typical Workflow

During development:

/qa                     # quick check on changed files
/qa e2e-gen             # generate E2E tests for UI changes (opt-in)
/qa visual              # visual regression check (opt-in, needs dev server)Copy

Before shipping:

/qa full                # comprehensive check across all files
/precheck               # local CI in 30s
/pr                     # create PR with QA resultsCopy

After deployment:

/qa staging             # validate staging deployment
/qa prod                # read-only production health checkCopy

Related Skills

QA Knowledge Base

The QA system learns from past runs:

• qa-knowledge/bug-patterns.md — patterns that caught real bugs
• qa-knowledge/coverage-gaps.md — persistent test gaps
• qa-knowledge/flaky-tests.md — tests that pass/fail inconsistently
• qa-knowledge/incidents/ — past incidents in affected files

Use /qa-learn to review stats and prune stale entries.

Installing QA

The prism bundle includes the full QA suite:

/plugin install prism@arthaiCopy

Or get everything with prime:

/plugin install prime@arthaiCopy

Auto-generated on 2026-07-05

Monitor-Powered Watchers

Get woken up on CI failures, deploy crashes, and runtime error spikes — without polling for them yourself. The agent then walks you through the fix; it does not apply fixes without your say-so.

How it works

Claude Code's Monitor tool registers background watchers that fire on external events (CI failure, deploy crash, error threshold breach). Zero token cost while idle. Wakes only when something happens, shows you what fired, and suggests the right next command (/ci-fix, /restart, /sre, etc.) — you decide whether to run it.

Setup

Step 1 — Update the toolkit

In Claude Code (skip if auto-update is enabled):

/plugin marketplace update arthai
/plugin uninstall <your-bundle>@arthai   # then reinstall, e.g. prime
/plugin install <your-bundle>@arthai
/reload-pluginsCopy

Then fully quit and reopen Claude Code. A running session loads its command list at startup, so a newly added command won't appear from /reload-plugins alone — only a full restart (quit the app/CLI completely, not /clear) rebuilds the command set.

Step 2 — Go to your project directory

cd /path/to/your/projectCopy

Step 3 — Start a watcher with /monitor

/monitor doesn't need any project detection step — just tell it what to watch:

/monitor logs <service>          # watch a service's log output for error patterns
/monitor pr <owner/repo>         # watch a GitHub repo for PR state changes
/monitor deploy <service>        # watch deployment health
/monitor ci                      # watch CI run resultsCopy

Each subcommand writes a watcher script to .claude/monitors/ and registers it with Claude Code's Monitor tool. There is no separate config-generation step — /monitor <subcommand> does the setup directly, and confirms with a summary of what it's watching and how to stop it (/monitor stop [<watcher-id>]).

Step 4 — Done

From this point, the watcher runs in the background at zero token cost until it sees a match.

Monitor is intentionally hands-on-the-wheel: it replaces polling loops with an event-driven wake-up, but every remediation step still needs your confirmation.

Nothing breaks

/ci-fix, /sre, /fix, /qa, and /pr work exactly as before — a Monitor watcher just adds an event-driven wake-up on top. If you never start a watcher, behavior is unchanged.

Stopping a watcher

/monitor stop <watcher-id>   # stop one watcher
/monitor stop                # stop all active watchersCopy

/monitor with no arguments shows usage and lists currently active watchers (read from .claude/monitors/.active).

Which bundle includes /monitor

If your bundle doesn't include /monitor, switch to prime (Step 1 above) to get it.

Supported watch sources

There's no webhook or platform-specific config to wire up — each subcommand writes a small bash watcher script and polls or tails the relevant source directly.

Workflow Comparison — Which Skill Should I Run?

The toolkit ships several orchestration workflows. They overlap in places and diverge in others. This guide answers two questions:

1. Given my situation, which one should I run?
2. What does each one actually do, and what does it produce?

Looking for the catalog of every skill? See skills-reference.

TL;DR Decision Tree

What do you have?
│
├── A clear goal but no clear plan? ─────────────────► /goal <objective>
│       e.g. "Cut homepage LCP under 2s"
│       e.g. "Make this endpoint return paginated results"
│
├── A backlog of issues to drain? ───────────────────► /autopilot
│       e.g. "Work through these 8 issues while I'm away"
│
├── A spec / well-defined feature to ship? ──────────► /planning → /implementation-plan → /implement
│       e.g. "Refactor the auth module per this PRD"
│       e.g. "Add user avatars (acceptance criteria below)"
│
├── A specific bug to fix (with reproduction)? ──────► /fix
│       e.g. "Fix #141 short session credit refund"
│
├── CI is broken? ───────────────────────────────────► /ci-fix
│       e.g. "build is red on main"
│
├── Need to deploy something? ──────────────────────► /deploy
│       e.g. "ship this to staging"
│
├── A tweet I want to evaluate as a feature? ────────► /monitor-tweet
│       e.g. "@anthropic just announced X — relevant?"
│
└── Already mid-session and lost track? ────────────► /continue
        re-reads state, picks up where you left offCopy

The distinction that trips people up most: /goal vs /autopilot vs /implement.

The Workflows

/goal — Speed-First Single Objective

When to use it: You know where you want to land but not how to get there. Exploratory, single objective. Fast.

How it works:

/goal <objective>
   │
   ▼
SCOUT  ── reads .claude/knowledge/shared/* + project-profile.md + prior goals FIRST,
   │      then targeted codebase scan to fill gaps
   ▼
CLARIFY  ── 3-5 context-aware questions (skips what the KB already answered)
   │      ◄── user answers (or "go" for defaults)
   ▼
CONFIRM PLAN  ── present clarified plan, wait for y/n/d
   │      ◄── user says "y"
   ▼
LOOP: pick action ──► execute ──► VERIFY (mandatory: lint + types + tests)
   │                                       ──► capture evidence (with verified flag)
   │                                       ──► self-evaluate done_when
   │  (auto-continue between turns via Stop hook)              │
   ▼                                                            ▼
all subtasks done + all evidence verified + requirements satisfied
   │
   ▼
ready for /pr (HARD STOP) ──► after /pr: append to goals-history.mdCopy

Example:

/goal Cut homepage LCP below 2s on mobileCopy

→ Scout reads app/page.tsx, identifies hero image and analytics blocker, proposes 4 subtasks each with done_when clauses, kicks off the first action. After 5–7 turns of scout → edit → test → measure, stops at PR creation.

State: .claude/.goals/current.json (one active goal at a time) Stops at: PR creation (you run /pr yourself) Auto-continues between: every turn, via goal-auto-continue Stop hook Lifecycle: /goal pause, /goal resume, /goal clear, /goal status Produces: branch, commits, evidence log, PR-ready summary

Best for: "Make X happen" objectives where the what is clear but the how is exploratory.

/autopilot — Rigor-First Backlog Loop

When to use it: You have a queue of issues and want them worked through with risk gating, evidence capture, and a PR per item.

How it works:

/autopilot
   │
   ▼
ASSESS ─► CLASSIFY ─► VERIFY ─► PLAN ─► IMPLEMENT ─► QA ─► SELF-REVIEW ─► PR
   │       (P0–P5)    (risk    (repro?)        ▲                            │
   │                   0–12)                   │                            │
   │                                           │                            ▼
   ▼                                           │                       AWAITING_MERGE
priority_queue                                 │                            │
                                               └─ auto-continue between ────┘
                                                  phases via Stop hookCopy

Example:

/autopilot --urgent-firstCopy

→ Ranks open issues P0–P5, picks the most urgent, scores blast-radius/ reversibility/confidence/domain-sensitivity (0–12), refuses if score >= 11, escalates if >= 9, otherwise verifies repro, plans, implements with the right team (backend/frontend/QA agents as needed), runs tests, scope-guards, creates PR. Stops for merge approval. After merge, picks the next item.

State: .claude/.workflow-state.json Stops at: PR creation per item (mandatory human gate); blocks on risk escalation, scope drift, QA failures after 2 attempts, or per-item budget breach (>6 agents). Auto-continues between: assess → classify → verify → plan → implement → qa → self-review → pr (via autopilot-auto-continue Stop hook). Stays silent at human-gate phases (awaiting_merge, blocked, paused). Evidence: evidence[] array — git-diffs, test results, lint, types, PR link, review status. PR body is assembled directly from evidence (no recall). Completion criteria: completion_criteria[] — each criterion has a done_when clause the model self-evaluates against captured evidence. Produces: PR per item, evidence trail, session summary

Best for: Backlog burndown when you want a consistent process per item, and the items are well-shaped enough to not need bespoke planning.

/planning — PRD Generation (Phase 1 of 2)

When to use it: You have a feature to build and want a written PRD (user stories, journey, edge cases, success criteria) before any architecture decisions are made.

How it works: spawn a product-manager (Sonnet) to write the PRD, with a brief feasibility-only note from the architect (no API design, no task breakdown, no debate). Design Thinker feeds UX context into the PM by default (skip with --no-design); GTM Expert can contribute positioning (--gtm).

Produces: .claude/specs/<feature>.md — the PRD, plus a design spec HTML by default.

Best for: Getting the user stories and scope reviewed before spending a debate cycle on architecture. Follow with /implementation-plan once the PRD looks right.

/implementation-plan — Architecture & Design (Phase 2 of 2)

When to use it: You have a reviewed PRD (from /planning) and want the full architecture debate before code is touched.

How it works: reads .claude/specs/<feature>.md → spawns architect (Opus) + product-manager (Opus) + Devil's Advocate → debates tradeoffs → finalizes plan. --design adds Design Thinker + Design Critic; --gtm adds a GTM Expert. --fast/--lite/--lite-strict control debate depth (see Arguments & flags).

Produces: .claude/plans/<feature>.md with scope, milestones, files, risks.

Best for: Non-trivial features where the plan itself is the deliverable.

/implement — Spec-Driven Team Build

When to use it: You have a plan (from /planning → /implementation-plan, or hand-written at .claude/plans/<feature>.md) and want a team to build it.

How it works: read the plan → spawn parallel agent team (backend + frontend + QA + red team) → each agent owns its layer → QA validates → red team challenges → finalize → ready for /qa commit and /pr.

Produces: code, tests, ready for PR.

Best for: Multi-layer features once a plan exists. Heavier than /goal — appropriate when you want explicit per-agent ownership and a paper trail of debate.

/fix — Formal Bug-Fix Pipeline

When to use it: A specific bug with a reproduction or issue number.

How it works: RCA → scope lock → behavior contract → fix → differential test → regression proof.

Produces: minimal-scope fix, regression test, PR.

Best for: Targeted bugs where you want guard-rails preventing scope creep.

/ci-fix — CI Failure Remediation

When to use it: CI is red and you want it fixed without manual debugging.

How it works: fetch failing run → diagnose → fix → re-run (3 attempts max). Exhausted? → Discord alert + escalate.

Produces: fix commits, green CI (or escalation).

Best for: Build-on-fire situations.

/deploy — Deployment Pipeline

When to use it: Ready to ship to local, staging, or preview.

How it works: read /calibrate deployment knowledge → run platform- specific deploy → post-deploy health check → report.

Produces: deployed environment, health-check evidence.

Best for: Routine deploys. Refuses production — those go through your team's review process.

/monitor-tweet — Tweet-to-PR Pipeline (partner installs only — requires source-repo access)

When to use it: You saw a tweet about a feature/idea and want to evaluate whether the toolkit should adopt it.

How it works: TRIAGE (extract idea, research feasibility, audit toolkit + arth) → present findings + BOTH repo options → user approves target + direction → build → review → /pr (auto).

Produces: PR (toolkit or arth) implementing the tweet's idea.

Best for: Triaging external feature ideas without manually researching every one.

Quick Reference: Example Scenarios

Auto-Continue & State

Both /goal and /autopilot use Stop hooks that nudge the model to auto-continue between phases without the user having to type "continue":

• goal-auto-continue (Stop) — fires when .claude/.goals/current.json shows an active goal with auto_continue: true and unfinished subtasks.
• autopilot-auto-continue (Stop) — fires when .claude/.workflow-state.json shows mode: autopilot and a non-human-gate phase.

Both hooks stay silent at human-gate moments (PR review, blocked, paused, awaiting merge, done). Both have loop-guards: after a fixed number of consecutive Stop events with no progress (12 for /goal, 15 for /autopilot), the hook bails and waits for the user.

The triage-router (UserPromptSubmit) detects active state and routes follow-up messages back to the active workflow. If the user types an unrelated slash command, the active workflow auto-pauses and the new request runs normally.

State files:

Choosing Between /goal and /autopilot

Both are autonomous loops. Both stop at PR creation. Both auto-continue. The difference is shape of the work:

If your work is "I have a destination, figure out the path" — that's /goal.

If your work is "I have a stack of well-scoped tickets, work them" — that's /autopilot.

If your work is "I have a written spec, build it" — that's /implement.

Bypass Permissions

Permission prompts are Claude Code's safety net: before writing a file or running a shell command, Claude asks you to approve. That's useful in interactive sessions — but it stalls subagents, pipelines, and Cowork Dispatch tasks that have no human in the loop to click Allow.

Bypass permissions mode disables the prompts entirely for a session. Every file edit, bash command, and tool call proceeds without asking.

When you need it

If your sessions hang waiting for approval, or your pipelines time out mid-task, bypass permissions is what you need.

How it's configured in this repo

This repo's .claude/settings.json includes:

{
  "permissions": {
    "defaultMode": "bypassPermissions"
  },
  "skipDangerousModePermissionPrompt": true
}Copy

defaultMode: bypassPermissions — all Claude Code sessions that load this project's settings start in bypass mode automatically. This applies to the main session, all subagents, and any start_code_task session pointed at this directory.

skipDangerousModePermissionPrompt — suppresses the one-time "are you sure you want to enter dangerous mode?" dialog. Without this, the first session still stalls on that confirmation.

The permissions block is preserved by install.sh's hook-merge logic, so it survives future toolkit upgrades.

How to enable it in your project

Option 1 — Project-level (recommended for automation)

Add to your project's .claude/settings.json:

{
  "permissions": {
    "defaultMode": "bypassPermissions"
  },
  "skipDangerousModePermissionPrompt": true
}Copy

Commit this file. Every session against that repo — yours, your teammates', CI agents — inherits it automatically.

If your .claude/ directory is gitignored (common when using the toolkit), force-add the file:

git add -f .claude/settings.json
git commit -m "chore: enable bypass permissions for automated sessions"Copy

Option 2 — CLI flag (per-session)

For a single session without touching settings:

claude --dangerously-skip-permissionsCopy

Or for a non-interactive run:

claude -p "your prompt here" --dangerously-skip-permissionsCopy

Option 3 — Global user settings

Add to ~/.claude/settings.json to enable bypass for every project on your machine:

{
  "permissions": {
    "defaultMode": "bypassPermissions"
  },
  "skipDangerousModePermissionPrompt": true
}Copy

Use this if you want bypass everywhere, not just in one repo.

Security considerations

Bypass permissions means Claude Code will run any bash command or write any file without asking. That's a real reduction in human oversight. Before enabling it:

Use it when:

• You trust the agent and the repo it's operating on
• You're running automated pipelines where no human can approve mid-session
• The repo is under version control and you can review + revert changes afterward

Don't use it when:

• Working in a repo that contains credentials, production configs, or sensitive data
• You're trying a new agent or prompt you haven't tested
• The session has access to external systems (email, databases, payment APIs) where an accidental action can't be undone

Mitigations if you use bypass broadly:

• Keep .env and secrets files in .gitignore so an accidental write doesn't commit them
• Use the pre-bash-guard hook (installed with the shield bundle, included in prime) — it blocks genuinely destructive commands like rm -rf / even in bypass mode. Check it's present if you rely on it as a bypass-mode safety net
• Run in a git repo so every file change is recoverable via git restore

How subagents inherit bypass

When a parent Claude Code session spawns a subagent (via the Agent tool), the subagent runs within the same session context and inherits the project settings.json. You don't need to pass any special flags — if the project has defaultMode: bypassPermissions, every subagent in that session runs with bypass too.

For Cowork Dispatch start_code_task sessions, Claude Code starts a fresh session pointed at the project directory. It loads settings.json from that directory on startup, so the same inheritance applies.

FAQ

General

Q: Do I need a license key? Yes. Without a valid key, the plugin installs but skills and hooks are non-functional. Email productive@getarth.ai to get a key.

Q: How does license validation work? On every prompt you send in Claude Code, a hook validates your key. First time it calls the license server (~200ms). After that it uses a 24-hour cache (~5ms).

Q: Can I use the plugins offline? Yes, after the first validation. The 24-hour cache means you can work offline as long as you validated within the last day.

Q: What happens if my key is revoked? Skills stop working within 24 hours (when the cache expires). Contact productive@getarth.ai for a new key.

Installation

Q: Skills aren't showing after install Run /reload-plugins and restart Claude Code.

Q: "LICENSE REQUIRED" on every prompt Run npx arthai-activate ARTH-XXXX-XXXX-XXXX-XXXX in your terminal (not Claude Code).

Q: How do I update the plugins (skills, agents, hooks) to the latest version? Easiest: turn on auto-updates once — run /plugin, open the Marketplaces tab, select arthai, choose Enable auto-update. Manual update:

/plugin marketplace update arthai      # refresh the catalog
/plugin uninstall <your-bundle>@arthai # then reinstall, e.g. prime
/plugin install <your-bundle>@arthai
/reload-pluginsCopy

What changed: see the CHANGELOG.

If the update doesn't seem to take, fall back to the full reset — remove the marketplace, clear the cache, re-add, and reinstall:

/plugin marketplace remove arthai
rm -rf ~/.claude/plugins/cache/*arthai*
/plugin marketplace add ArthTech-AI/arthai-marketplace
/plugin install <your-bundle>@arthai
/reload-pluginsCopy

Q: How do I update Arth Intelligence (the local Docker container)? Two ways, both safe — your trace data is preserved either way.

Automatic. If you installed via /otel-setup, a watchtower sidecar checks once a day and pulls the latest arthai/intelligence image. You don't need to do anything.

Manual (force update now). Run:

curl -fsSL https://arthtech-ai.github.io/__ARTH_MARKETPLACE__/scripts/update.sh | shCopy

Or paste these two commands if you prefer not to pipe to shell:

docker compose -f ~/.arthai/docker-compose.yml pull
docker compose -f ~/.arthai/docker-compose.yml up -dCopy

Never run docker compose down -v unless you intentionally want to wipe all trace data (e.g. the uninstall path) — the -v flag drops the data volume and erases every session, score, and pattern. Plain down (without -v) is safe; it just stops the containers.

See Step 7h: Updating Arth Intelligence for the full picture (skill updates, compose-file updates, opt-out of auto-updates).

Usage

Q: Which bundle should I start with? Start with prime — the everything bundle (it's what the Quick Start installs). If you want a smaller footprint, forge covers the core development workflow (planning, implementing, QA, PRs); add more bundles as needed.

Q: Can I install multiple bundles? Yes. Bundles compose without conflicts.

Q: What does /calibrate do? It scans your codebase and configures the toolkit to match your project's tech stack, patterns, and conventions. Safe to run multiple times.

Q: Can I override plugin behavior? Yes. Project-local files in .claude/agents/ and .claude/skills/ take precedence over plugin-provided ones of the same name. See Configuration for details.

Troubleshooting

Q: CLAUDE.md not created after install Restart Claude Code — the setup hook fires on session start, not on install.

Q: Old version seems stuck Clear the plugin cache: rm -rf ~/.claude/plugins/cache/*arthai* then reinstall.

Q: A skill is erroring out Check that your license is valid (cat ~/.arthai/license), then try /reload-plugins and restart Claude Code.

Observability

Full guide — what Arth Intelligence is, setup, verification, dashboard tour, privacy: arth-intelligence.md

Q: Why are the cost / token columns empty in the dashboard? Cost and token data only flow when Claude Code's native OTEL is enabled. The toolkit hook emits structural spans (sessions, prompts, tool calls, agent spawns) but does not emit cost metrics — that's the native emitter's job. Verify the env var is set:

grep CLAUDE_CODE_ENABLE_TELEMETRY .claude/settings.local.jsonCopy

If missing, run /otel-setup and pick "Local" — it writes CLAUDE_CODE_ENABLE_TELEMETRY=1 along with the OTLP endpoint and protocol (http/json) into .claude/settings.local.json. Restart Claude Code, run any prompt, and the cost columns populate from that point forward.

If the var is set but cost is still empty, also check OTEL_EXPORTER_OTLP_PROTOCOL=http/json is present — without it, Claude Code defaults to gRPC/protobuf and the engine silently drops the metrics.

Q: My dashboard shows everything as "Unattributed" (no Toolkit / Claude / custom-agent split) Your OTEL emitter is pointing at the wrong engine or protocol, so the owner labels never reach the dashboard — and on older installs it failed silently. This is usually a stale .claude/.arth-otel.env (the file the emission hook reads) left over from an earlier setup, holding an old port or http/protobuf instead of http/json.

Fix — three steps, ~1 minute:

1. Update the toolkit to the latest plugin version.
2. Update Arth Intelligence — it auto-updates via watchtower, or run docker compose pull && docker compose up -d (the turn_cost_facts table is created automatically on startup).
3. Run /otel-setup once, then restart your Claude Code session. /otel-setup now detects and repairs a stale .arth-otel.env, reconciles it with settings.local.json, validates the endpoint is reachable on http/json, and runs a smoke test. You'll also get a one-line warning at session start if the endpoint is unreachable, so this can't silently bite you again.

Attribution is forward-only: only sessions run after you correct the config are attributed by owner. Sessions captured earlier stay "Unattributed" — that's by design, not a bug.

Q: Where does the dashboard live? After /otel-setup finishes, it's at http://localhost:3100. Engine health is at http://localhost:4319/api/health.

Q: What's the difference between the toolkit's OTEL hook and Claude Code's native OTEL? Both stream into the same local engine and complement each other:

You want both on for a complete dashboard. /otel-setup enables both in one step.

Q: Can I disable observability? Yes. export OTEL_DISABLED=true makes the toolkit hook a no-op. Native OTEL is gated separately by CLAUDE_CODE_ENABLE_TELEMETRY — unset it (or set to 0) to stop native cost/token streams.

Q: Why is my dashboard empty after a reboot? Most likely your engine + DB containers aren't running. Check:

docker ps --filter 'name=arthai'Copy

You should see three containers — arthai-intelligence, arthai-db, arthai-watchtower. If any are missing, your compose file probably has an old restart policy (only watchtower had restart: unless-stopped before the reboot-durability fix). Two ways to fix:

# Fastest — just update the running containers in place
docker update --restart unless-stopped arthai-db arthai-intelligence

# Or re-run /otel-setup → Local — overwrites ~/.arthai/docker-compose.yml with the
# new template that sets restart: unless-stopped on every serviceCopy

Either way, no data loss — the arthai_data Docker volume is preserved across all container changes.

If Docker Desktop itself didn't start, that's a per-user OS toggle: open Docker Desktop → Settings → General → "Start Docker Desktop when you log in." We can't set this for you.

Q: What survives a reboot vs what doesn't? See getting-started.md → Step 7g: What survives a reboot for the full table. Short version: env vars + compose file + your trace data all persist; what was running depends on whether your containers have restart: unless-stopped (current /otel-setup templates set this; verify with docker inspect --format '{{.HostConfig.RestartPolicy.Name}}' arthai-intelligence).

/autopilot

Autonomous work loop — picks up issues, implements, QAs, PRs. Stops for merge approval.

Synopsis

/autopilot [issue_number] [--dry-run] [--urgent-first|--least-first]Copy

When to use it

• You have a backlog of GitHub issues and want them worked methodically: assess → classify risk → verify → plan → implement → QA → self-review → PR
• You want a junior-engineer workflow with guardrails — risk scoring before any code, escalation when unsure, and a mandatory human gate at every PR
• Not for: one open-ended objective where the path is unknown — that's /goal, the speed-first single-objective loop; /autopilot is rigor-first and queue-driven, with full P0–P5 ranking and per-item risk classification
• Not for: a single bug you already understand — /fix is faster

Quickstart

/autopilot --urgent-firstCopy

What you'll see: the open issues and PRs ranked P0–P5, then the loop starts on the most urgent item. It self-paces through implementation and QA, opens a PR, and stops — it never merges. After you merge, it picks up the next item automatically.

Examples

/autopilot                  # rank the backlog, ask which direction to work
/autopilot 141              # work just issue #141
/autopilot --urgent-first   # P0 → P5: critical items first (recommended default)
/autopilot --least-first    # P5 → P0: warm up on small items
/autopilot --dry-run        # show the ranked queue and plan without doing anythingCopy

Arguments & flags

What it does

1. Assess — scans open issues, your PRs, and review comments; ranks everything P0 (critical) to P5 (nice-to-have) using labels and impact rules. If no direction flag was given, it asks you — user-confirmation checkpoint. Vague issues without acceptance criteria are flagged for your triage, never auto-picked.
2. Classify risk — scores blast radius, reversibility, confidence, and domain sensitivity (0–12). Low risk proceeds autonomously; 6–8 proceeds with notice; 9–10 stops and asks — user-confirmation checkpoint; 11–12 is refused. Migrations and auth/payment code always escalate.
3. Verify — reproduces the bug before touching code; stale already-fixed issues get closed instead of "fixed" again.
4. Plan — defines expected files/layers and objective completion criteria (each with a verifiable done_when clause).
5. Implement — simple fixes inline; multi-file work via backend/frontend agents plus a QA agent. Every commit and test run is captured in an evidence log.
6. QA — runs tests, lint, type checks (2 fix attempts max, then it escalates).
7. Self-review — a separate gate after QA passes: checks scope growth (>1.5x planned stops the loop), hardcoded values, error handling, security, test coverage, and unintended changes; re-assesses risk now that code exists. Unrelated bugs found along the way are filed as issues, not fixed inline.
8. PR — mandatory stop — opens a PR whose body is assembled from the evidence log, then stops and waits for your merge approval — user-confirmation checkpoint. It never merges. While waiting, it pre-assesses the next item.
9. Post-merge — checks CI on main (auto-reverts and reopens the issue if its merge broke CI), records learnings, then loops to the next item. Once this completes, a completion-verifier agent checks the item's evidence against its completion criteria (see below).

Agents spawned

architect (opus) is not spawned directly by autopilot — for risk-6+ features, Phase 4 (PLAN) delegates to the /planning skill, which spawns architect itself.

Post-merge verification: after a work item's full lifecycle completes, autopilot spawns completion-verifier (sonnet) to check the item's evidence against its completion criteria. It reports PASS, GAPS FOUND, or INCONCLUSIVE — gaps don't block, you decide whether to rerun.

Output & artifacts

• One PR per work item, with risk assessment, scope check, evidence, and QA results in the body
• .claude/.workflow-state.json — durable loop state: queue, current item, evidence, session summary (resume anytime with /autopilot)
• Issues filed for problems discovered along the way; learnings appended to .claude/knowledge/skills/autopilot.md

Troubleshooting

Related

• /goal — single-objective, speed-first counterpart; both stop at PR creation
• /fix — the formal bug pipeline autopilot's rigor is modeled on
• /pr — manual PR workflow for work you drive yourself
• /tech-debt — autopilot auto-runs an audit every 3 completed items

/brainstorm

Grounded thinking partner — turn a vague thought, question, or "help me understand this" into clarity, anchored in this repo's calibrated knowledge base (populated by running /calibrate first — the skill still works on uncalibrated projects, but answers lean more generic).

Synopsis

/brainstorm [thought | question]Copy

Alternate invocations: /help me think, /wondering, /what if, /should we even, /not sure — all trigger the same skill.

When to use it

• You don't know what you want yet — a half-formed idea, a "should we even do this?", a "what if we…"
• You want a grounded explanation of how something in this repo works, not generic advice
• You're weighing a direction and want your hidden assumptions surfaced before you commit
• Not for: committing to build a specific feature — that's /planning; fixing a known bug — that's /fix; knowing you're building X and wanting the design nailed down before coding — that's superpowers:brainstorming (it ends by writing a design doc). /brainstorm is for when you don't know what you want yet — it's upstream of intent; it routes you to those other skills once your thinking sharpens.

Quickstart

/brainstorm I keep thinking we should refactor the payments moduleCopy

What you'll see: one clarifying question, a reflection grounded in your project's calibrated knowledge (cited from project-profile.md, conventions.md, domain.md, etc.), an explicit "in this repo X / generically Y" contrast, one or two hidden assumptions called out, and a closing choice — dig deeper, converge to a summary, or hand off to the right skill. It never writes code or files on its own.

For example, on a direct question, one line of the reply looks like:

In this repo: we have inbox-queue (Redis, at-least-once) and system-bus (Kafka, exactly-once).
Generically: the tradeoff is operational simplicity vs delivery guarantees and replay-ability.Copy

When your intent sharpens, /brainstorm offers (never auto-invokes) the matching downstream skill:

Examples

/brainstorm what's the difference between our two queue systems?   # grounded explanation, repo-vs-generic
/brainstorm what if we let users tag projects with custom labels?  # half-formed idea → probes intent, may steer to /planning
/brainstorm should we even build a mobile app?                     # existential — stays in /brainstorm, that's the job
/brainstorm                                                        # no args → prompts "What's on your mind?"Copy

What it does

1. Loads the knowledge base first (a hard contract) — reads .claude/project-profile.md, .claude/knowledge/shared/*.md, .claude/knowledge/external/sources.md, and CLAUDE.md before answering, so every response is grounded in (or explicitly contrasted against) project reality. The skill works on any project — it just gives grounded, repo-specific answers only if your project has been calibrated via /calibrate first; otherwise it says so up front and leans generic. A size guard lazy-loads deep content for very large KBs.
2. Parses your input — categorizes it (question, vague thought, half-formed idea, comparison, existential, bug symptom) to shape the turn.
3. Answers in a fixed turn template — one clarifying question (max), grounded reflection with citations, explicit repo-vs-generic labeling, 1–2 surfaced assumptions, and a closing choice.
4. Watches the handoff radar — when your intent crystallizes, it offers the right downstream skill (/planning, /implement, /fix, /explore, /tech-debt, /perf, …) but never auto-invokes it — a user-confirmation checkpoint.
5. Converges on request — produces a compact, paste-ready "Where we landed" summary, then offers to write a durable insight back to the knowledge base (conventions / domain / patterns / vocabulary). Never auto-writes; skipped entirely for pure lookups.

If the project hasn't been calibrated (no project-profile.md), it says so up front and notes its answers will lean generic — run /calibrate first for repo-grounded responses.

Output & artifacts

• No files written by default — /brainstorm is a thinking mode, single-agent, no fan-out.
• On convergence: a paste-ready summary block in the conversation.
• Optional, only if you accept the offer: a few-line dated entry appended to .claude/knowledge/shared/<area>.md.
• On an accepted handoff: control passes to the chosen skill, which owns its own outputs.

Cost

Negligible (~2 units) — a single agent, no fan-out, one set of parallel file reads on entry (bounded by a size guard so large knowledge bases lazy-load instead of front-loading), then turn-based responses. An accepted handoff to another skill bears that skill's own cost, and an accepted knowledge-base write-back at convergence is a single small append. /brainstorm is deliberately cheap so it can be the friction-free front door.

Troubleshooting

Related

• /onboard — when you want a prioritized briefing on what to work on, not open-ended thinking
• /planning — the usual handoff once a /brainstorm idea crystallizes into a feature
• /calibrate — populates the knowledge base that /brainstorm grounds its answers in
• Workflow comparison — where /brainstorm sits among the toolkit's entry points

/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]Copy

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 <!-- TODO --> placeholders). If it's missing or incomplete, /calibrate automatically runs /scan first.

Quickstart

/calibrateCopy

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 stackCopy

What it does

1. 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 <!-- TODO --> placeholders.
2. Phase 1 — scan: a scanner agent deep-reads the project — platform, architecture patterns, coding conventions, testing patterns, domain model, integrations, environments.
3. Phase 2 — evaluate: an evaluator agent scores every toolkit agent, skill, and hook against the scan and identifies gaps and recommended workflows.
4. Phase 3 — profile: a profiler agent writes .claude/project-profile.md (diff mode on rescan — only changes, manual sections preserved).
5. 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.
6. 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.
7. 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.
8. Phase 6 — verify (inline): confirms MCP servers in settings, categories installed, profile and knowledge base written, then prints the completion report.
9. 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

(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 likeCopy

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

Related

• /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

/ci-fix

Auto-remediate CI, staging, and production failures. 3-attempt retry with investigation. Discord alert on exhaustion.

Synopsis

/ci-fix [ci|staging|prod] [branch]Copy

When to use it

• CI went red on your branch — lint, type, test, build, migration, or dependency failures
• A staging deploy failed and you want it diagnosed and patched
• A production deploy failed — prod mode investigates read-only first and never touches the prod database
• Not for: a logic bug in your code with green CI — that's /fix; or pre-push validation — that's /precheck

Quickstart

/ci-fixCopy

What you'll see: the failed run's logs pulled and classified, a narrowly-scoped fix verified locally, then a commit + push and a wait for the new CI result. If the first attempt doesn't go green, it retries with a different strategy — up to 3 attempts.

Examples

/ci-fix                        # fix CI failures on the current branch
/ci-fix ci feature/my-branch   # fix CI on a specific branch
/ci-fix staging                # diagnose + fix a staging deploy failure
/ci-fix prod                   # production deploy failure — read-only investigation firstCopy

Arguments & flags

What it does

1. Reads the full CI/CD landscape — CLAUDE.md test commands and the project profile, then checks the knowledge base and knowledge graph using keywords from the error logs (if kg-query.sh is available, it runs first and surfaces past CI failure patterns, known flaky tests, and team conventions before investigating from scratch). It then detects the actual CI platform via config files (.github/workflows/, .gitlab-ci.yml, Jenkinsfile, .circleci/config.yml, and others) and uses platform-specific commands to pull logs, check status, and retry — for non-GitHub CI, review your CLAUDE.md test/CI commands, since most guidance below assumes GitHub Actions conventions. It also checks for environment mismatches between CI and local: runtime versions (python/node/go), running services (postgres, redis), env vars, and secrets — if tests pass locally but fail in CI, this is the first place to look.
2. Checks known flaky patterns — before investigating, it queries past CI incidents and the bug-pattern database in the knowledge base. If a match is found, it reports the known issue instead of redoing the investigation; if it's a new pattern, it gets added to the knowledge base for future /ci-fix runs.
3. Attempt loop (max 3) — each attempt: pull the failed logs, classify the failure (lint / types / tests / build / migration / dependency), apply a fix scoped to only the failing files, verify locally before pushing, then commit, push, and wait for the new CI result. Each retry uses a different strategy — attempt 2 reads more context, attempt 3 does a deep investigation against the last green commit.
4. Mode-specific guardrails — staging mode reads deploy logs and health endpoints, patching code or env vars; prod mode is read-only first, never modifies the production database, and considers a git revert on attempt 3.
5. On exhaustion — after 3 failed attempts it posts a Discord alert to #deployments (when discord-ops is configured), writes a QA incident file, and hands back to you for manual review.
6. Completion verification — a completion-verifier agent runs a final cross-check, displaying PASS (fully fixed), GAPS FOUND (fix incomplete), or INCONCLUSIVE (unclear if fixed). GAPS FOUND does not block anything — you decide whether to rerun /ci-fix.

On the claude-agents toolkit repo specifically, CI failures often come from repo-specific conventions rather than real bugs: bracket characters in a SKILL.md description:/arguments: field (fix: use <text> not [text]), missing required frontmatter fields, a new portable.manifest entry not yet mapped to a category in install.sh:get_category_items(), or a stale agent test fixture (fix: cp agents/<name>.md tests/fixtures/claude-setups/poweruser/.claude/agents/). /ci-fix auto-fixes all of these when it recognizes them.

Hard rules: never repo-wide lint auto-fix, never # noqa/# type: ignore suppressions, never deleted or skipped tests, never direct deploy commands — fixes always go through git, never modify dependency files unless the failure is actually a dependency issue, and never run railway up or an equivalent platform deploy command — always push to git and let the platform auto-deploy.

Agents spawned

Output & artifacts

• Fix commits pushed to the branch (fix: <category> — <what was fixed>)
• .claude/monitors/.ci-fix-state.json — per-branch attempt counter that persists across sessions (Monitor-triggered runs). Monitor-triggered invocations check this file first: if attempts >= 3 for the branch, it skips remediation and sends a Discord alert instead of retrying; on a green CI result the branch's entry is removed (reset). This prevents runaway agent spawns on a persistently failing branch.
• Knowledge-base entry in .claude/knowledge/skills/ci-fix.md after every fix; on exhaustion, an incident file in .claude/qa-knowledge/incidents/
• Discord alert in #deployments when all 3 attempts fail (if configured)
• CI improvement recommendations (caching, parallelism, timeouts, flaky-test retries) after the fix

Troubleshooting

Related

• /precheck — catch these failures locally before CI ever sees them
• /fix — when the CI failure traces to a real code bug worth the formal pipeline
• /incident — triage entry point that routes to /ci-fix automatically
• /sre — deploy health checks and operations beyond CI
• Monitors — event-driven auto-remediation: wake /ci-fix on CI failure with zero idle cost

/client-discovery

Client discovery and AI readiness assessment.

Synopsis

/client-discovery <client-name> [-- brief]Copy

When to use it

• First substantive step with a new client — gathers business context, tech landscape, and pain points
• Producing an AI maturity score and readiness level to anchor the rest of the engagement
• Not for: deep competitive or industry research — that's /market-research; or running the whole engagement lifecycle — that's /consulting

Quickstart

/client-discovery acme-corpCopy

What you'll see: a structured intake interview (13 questions in three groups), followed by a current-state analysis, AI maturity scorecard, competitive research, and a set of discovery files written to the client's directory.

Prerequisites: WebSearch access must be enabled in your Claude Code settings — step 4 (competitive landscape research) runs ~8 WebSearch queries and will fail if WebSearch is not permitted. Run the command from the project directory where consulting-toolkit/ exists (typically the claude-agents root).

Examples

/client-discovery acme-corp                                   # full interactive intake
/client-discovery acme-corp -- 50-person fintech, Postgres + AWS, wants churn prediction
                                                              # brief pre-answers questions; only gaps are askedCopy

What it does

1. Intake interview — user-confirmation checkpoint: asks 13 questions via AskUserQuestion in three groups — Business Context (5), Current Technology (4), Pain Points & Goals (4). If you passed a -- brief, questions it already answers are skipped and the extracted answers confirmed with you. Declined questions are recorded as "Not disclosed".
2. Current state analysis — business model summary, a Mermaid tech-stack diagram, a Data Readiness Score (1-5 across Volume, Quality, Accessibility, Governance, Integration), and a team capability matrix.
3. AI maturity assessment — scores Strategy, Data, Technology, People, and Process 1-5 against a rubric; composite score (5-25) maps to a readiness level (Not Ready, Early Stage, Developing, Advancing, AI-Native Ready), presented as an ASCII scorecard.
4. Competitive landscape research — runs ~8 WebSearch API queries (industry AI trends, competitor initiatives, case studies with ROI) and compiles a competitive intelligence brief (max 500 words). Requires WebSearch to be enabled — see Prerequisites above.
5. Writes the discovery files — profile plus four discovery documents (see below). If the client directory already exists, it warns you and asks whether to overwrite or create a versioned copy.

The whole process takes roughly 15-20 minutes with a cooperative client.

Output & artifacts

All files land in consulting-toolkit/clients/<client-name>/:

• profile.md — company overview, business model summary, maturity score and readiness level
• discovery/intake.md — all 13 questions with verbatim answers
• discovery/current-state.md — business narrative, tech-stack diagram, data readiness scores, capability matrix
• discovery/maturity-assessment.md — dimension scores with justification, composite score, scorecard, recommended focus areas
• discovery/stakeholder-map.md — decision makers, influencers, champions, end users, blockers (templated with placeholders if not provided during intake)

Troubleshooting

Related

• /consulting — the engagement orchestrator; runs this as the discovery phase
• /opportunity-map — the next step: turns discovery data into scored initiatives
• /market-research — deeper, focused research beyond the discovery-phase scan

/cloud-setup

Configure the Arth dashboard's UI/cloud features — the "Explain this session" LLM key and the experimental Cloud Orchestrator (calibrate/plan a repo). Runs on top of a telemetry-only /otel-setup install.

Synopsis

/cloud-setupCopy

When to use it

• You ran /otel-setup (telemetry-only) and now want the dashboard's "Explain this session" AI summary
• You want to turn on the experimental Cloud Orchestrator (point Arth at a Git repo to calibrate or plan a feature live)
• You're adding an LLM key, GitHub token, or license to an existing Arth Intelligence install
• Not for: the OTEL telemetry stack itself (cost/token/session data) — that's /otel-setup, which stays telemetry-only

Quickstart

/cloud-setupCopy

What you'll see: a precheck that your local Arth Intelligence stack is healthy, then two optional questions — enable Explain (pick a provider/key) and enable the Cloud Orchestrator (collect the required secrets, write the override, pull the sandbox). You can enable just one, both, or skip both entirely. Telemetry is never touched.

CLI parity

The same interactive flow ships in the Arth CLI for terminals without the toolkit:

arth cloud-setupCopy

Install the Arth CLI first — it ships through the private Arth repo (gated by your GitHub access, no public package).

Examples

/cloud-setup        # the only form — the skill takes no argumentsCopy

Typical runs:

• Just want Explain → opt into Explain, pick a provider/key, decline the orchestrator → dashboard summaries turn on
• Want the full cloud experience → opt into Explain and the orchestrator → it writes the override, pulls the sandbox, and Runs / ☁ Calibrate a repo appear at http://localhost:3100
• No toolkit installed → run arth cloud-setup in a terminal for the identical flow

What it does

1. Precheck — Arth Intelligence must be running. Confirms Docker is up, ~/.arthai/docker-compose.yml exists (from /otel-setup → Local), and the engine is healthy on :4319. If not, it stops with the exact fix (run /otel-setup first, or start the stack).
2. Asks: enable "Explain this session"? (FIRST, and NOT experimental). A user-confirmation checkpoint. Optional and separate, API-billed (not your Claude Code subscription) — ~$0.001–0.002 per session on a small/flash model, or free with local Ollama / LM Studio. Pick a provider in plain language (Anthropic / OpenAI / Gemini / Ollama / LM Studio / Bedrock); it confirms your choice (e.g. "Anthropic, claude-haiku-4-5, ~$0.001/session") and estimated per-session cost, then saves the key/host to ~/.arthai/.env and recreates the dashboard to pick it up. LM Studio auto-detects the loaded model (e.g. qwen) — no model id needed. Skip it and the dashboard shows a small "needs an LLM key" prompt where the summary would go. (/otel-setup also offers to turn on Explain inline at the end of its own flow, right after it verifies telemetry — so you don't have to run this skill just for Explain.)
3. Asks: enable the Cloud Orchestrator? (experimental, off by default, Claude-only). A user-confirmation checkpoint. If you accept, it collects the required secrets and writes an additive ~/.arthai/docker-compose.override.yml (orchestrate flags + sandbox image + Docker-socket access — the base compose is untouched and reversible), pulls arthai/cloud-sandbox:latest, and recreates the dashboard with cloud enabled. The sandbox runs Claude only (for now), so it needs an ANTHROPIC_API_KEY — if your Explain choice in step 2 was Claude it's reused; if it was a non-Claude provider (or you skipped Explain) you're asked for a Claude key now (both keys are kept). It also needs ARTH_GITHUB_TOKEN + ARTH_LICENSE_KEY. Decline (default) and nothing changes.
4. Summarizes what's now on (Explain / Orchestrator) and confirms telemetry is unaffected.

Output & artifacts

• ~/.arthai/.env — the LLM key (Explain) and any orchestrator secrets, expanded by docker-compose. Survives image updates (pulls/Watchtower never remove it).
• ~/.arthai/docker-compose.override.yml — orchestrator flags + sandbox image + socket mount (only if you enabled the orchestrator). Delete it to turn the orchestrator off.
• A recreated arthai-intelligence container picking up the new config. Dashboard at http://localhost:3100.

Troubleshooting

To disable the orchestrator: delete ~/.arthai/docker-compose.override.yml and run docker compose -f ~/.arthai/docker-compose.yml up -d.

Related

• /otel-setup — the telemetry stack this builds on
• Cloud Orchestrator guide — full walkthrough of calibrate/plan a repo
• Arth Intelligence guide — what the dashboard shows
• Configuration → Explain this session

/consulting

Run a full AI consulting engagement.

Synopsis

/consulting [client-name] [--phase discovery|assess|propose|design|deliver|track] [-- brief]Copy

Prerequisites

Each phase delegates to a specialist skill — the phase will fail if its skill isn't installed:

Run /skills to confirm all six are installed before starting a full engagement — a missing sub-skill surfaces as a phase failure, not a clear "skill not found" message.

When to use it

• Starting a new client engagement — it creates the client workspace and walks the full lifecycle
• Resuming an engagement mid-stream — it reads the saved state and picks up at the current phase
• Getting a status report or a dashboard of all active engagements
• Not for: running a single activity in isolation — call the phase skill directly, e.g. /client-discovery or /roi-calculator

Quickstart

/consulting acme-corp -- AI readiness assessment for a mid-market logistics firmCopy

What you'll see: a new client workspace at consulting-toolkit/clients/acme-corp/ with engagement.json and a profile.md stub, then the discovery phase kicks off via /client-discovery.

Examples

/consulting acme-corp                          # resumes if engagement.json exists, else initializes at discovery
/consulting acme-corp --phase propose          # jump straight to the proposal phase
/consulting acme-corp -- brief context here    # new engagement with a free-text brief
/consulting                                    # no client name — dashboard of all active engagementsCopy

Note: /consulting <client-name> with no --phase flag doesn't always "resume" — it resumes only if consulting-toolkit/clients/<client-name>/engagement.json already exists. On a brand-new client name it initializes a fresh engagement at the discovery phase instead.

Arguments & flags

What it does

1. Loads or initializes engagement state — reads consulting-toolkit/clients/<client-name>/engagement.json if it exists and resumes from the current phase; otherwise creates the client directory, engagement.json (phase statuses, decisions, risks, value tracking), and a profile.md stub.
2. Routes to the active phase — each phase delegates to a specialist skill:

• discovery → /client-discovery — interviews, tech assessment, stakeholder mapping
• assess → /opportunity-map — maturity scoring, priority matrix
• propose → /pitch-generator + /roi-calculator — proposal and ROI models
• design → /solution-architect — architecture, build-vs-buy, sprint plan
• deliver → /deliverable-builder — final deliverables package, handoff docs
• track → /engagement-tracker — status reports, value tracking

1. Phase transition protocol — when a phase completes, it verifies completion criteria (deliverables produced, decisions logged, risks captured), updates engagement.json, and generates a phase transition summary. User-confirmation checkpoint: it always confirms with you before advancing to the next phase — it never auto-advances.
2. Status report on demand — at any point you can ask for an engagement status report (phase progress table, value summary, open risks, recent decisions, next actions) generated from engagement.json.
3. Multi-engagement dashboard — invoked with no client name, it lists all active engagements with phase, status, and projected value.

After each phase it prints a context-hygiene tip: start a fresh session per phase (/clear, then /consulting <client> --phase <next>) — engagement state lives in engagement.json, so nothing is lost.

Cost and time: a full 6-phase engagement runs ~200-300 units of model spend and spawns 7+ sub-skill invocations sequentially (one or more per phase), each of which may spawn its own agents. Expect this to be a multi-session effort — budget a session per phase rather than expecting one pass to finish everything.

Output & artifacts

• consulting-toolkit/clients/<client-name>/engagement.json — engagement state: phases, deliverables, decisions, risks, value captured (written by /consulting itself)
• consulting-toolkit/clients/<client-name>/profile.md — client profile (filled in across phases, written by /consulting itself)
• Per-phase deliverables written by the delegated skills (discovery notes, opportunity matrix, ROI models, proposals, architecture docs, tracking dashboards) under clients/<client-name>/ — note this is a different root than the consulting-toolkit/clients/ path above, since each delegated skill (/client-discovery, /opportunity-map, /pitch-generator, /solution-architect, /deliverable-builder, /engagement-tracker) manages its own output location. Always pass the exact same <client-name> to every phase skill, or later phases won't find earlier phases' files.
• Phase transition summaries and status reports in the conversation

Troubleshooting

Related

• /client-discovery — discovery phase: intake interview and AI readiness assessment
• /market-research — industry, competitor, and trend research
• /opportunity-map — assess phase: score and prioritize AI initiatives
• /roi-calculator — propose phase: financial models with sensitivity analysis
• /pitch-generator — propose phase: proposals, exec summaries, deck outlines
• /solution-architect — design phase: architecture and implementation plans
• /deliverable-builder — deliver phase: client-ready deliverables
• /engagement-tracker — track phase: progress, milestones, RAG status
• /magazine-generator — polished HTML magazine for product storytelling
• /templates — generic structured deliverables outside an engagement

/deliverable-builder

Build client-ready consulting deliverables.

Synopsis

/deliverable-builder <client-name> [--type final-report|status-update|board-deck|implementation-guide|training-plan|change-management|data-strategy]Copy

When to use it

• Assembling polished documents from engagement data — final reports, board decks, technical guides
• Producing periodic status updates or plans (training, change management, data strategy) during delivery
• Not for: pre-sale documents like proposals and pitch decks — that's /pitch-generator; or live progress dashboards — that's /engagement-tracker

Prerequisites

• A client profile at clients/<client-name>/profile.json
• Engagement data under clients/<client-name>/ (discovery, assessment, architecture, tracking subdirectories) — typically produced by running /client-discovery, /opportunity-map, /solution-architect, and /engagement-tracker for the client first
• Without this data, generated deliverables will have thin or empty sections

Quickstart

/deliverable-builder acme-corp --type final-reportCopy

What you'll see: a 12-section engagement report (executive summary through appendices) assembled from the client's discovery, assessment, architecture, and tracking data, written to clients/acme-corp/deliverables/final-report.md with word count and section list reported.

Examples

/deliverable-builder acme-corp                              # no type — prompts you to choose one
/deliverable-builder acme-corp --type final-report          # 15-30 page comprehensive engagement report
/deliverable-builder acme-corp --type board-deck            # 10-slide executive/board presentation outline
/deliverable-builder acme-corp --type status-update         # 2-5 page periodic progress report
/deliverable-builder acme-corp --type implementation-guide  # 10-20 page technical how-to for IT teamsCopy

Arguments & flags

What it does

1. Loads engagement context — reads all available data under clients/<client-name>/ (profile, discovery, assessment, architecture, tracking, prior deliverables) and extracts company name, engagement dates, primary contact, and initiative names.
2. Type selection — user-confirmation checkpoint: if --type was not given, it asks you to choose from the 7 deliverable types.
3. Generates the deliverable from the standard template for that type, pulling content from prior skill outputs:

• final-report — 12 sections for the executive sponsor: summary, methodology, current state, market analysis, recommendations, architecture, roadmap, ROI, risks, next steps, appendices
• status-update — RAG status by workstream, accomplishments, risks, decisions needed, next-period plan, key metrics
• board-deck — 10-slide outline ending in a specific ask and budget approval request
• implementation-guide — prerequisites checklists, step-by-step setup, configuration reference, testing, runbook, rollback procedures
• training-plan — skills assessment, three-track curriculum (all staff / power users / technical team), timeline, resources, success metrics
• change-management — stakeholder analysis, phased communication plan, resistance management, adoption metrics, support structure
• data-strategy — data landscape and maturity, governance framework, quality standards, migration plan, AI-specific data requirements

1. Quality gates — structure (version header, date, executive summary, TOC), content (citations, valid Mermaid, specific action items, realistic numbers), formatting (no leftover placeholders), and completeness checks before finalizing.
2. Versioned output — if the file already exists, the version number is incremented (1.0 → 1.1) and a change log entry added rather than silently overwriting.

Output & artifacts

• clients/<client-name>/deliverables/<type>.md — the generated deliverable
• A confirmation in the conversation: file path, word count, sections generated, and any quality-gate items needing manual review

Troubleshooting

Related

• /consulting — the engagement orchestrator; runs this as the deliver phase
• /pitch-generator — pre-sale counterpart: proposals and pitch documents
• /engagement-tracker — source of the tracking data behind status updates
• /solution-architect — source of the architecture content in reports and guides
• /templates — generic structured documents outside a client engagement

/deploy-ios

Build and deploy iOS apps to Simulator, TestFlight, or App Store. Auto-detects Xcode project config, resolves signing, and validates builds.

Synopsis

/deploy-ios [simulator|testflight|appstore] [--device name] [--scheme scheme]Copy

--clean is also accepted to force a clean build.

When to use it

• Running your iOS/iPadOS app in the Simulator to check a change
• Archiving and uploading a build to TestFlight for beta testers, or to App Store Connect for review
• Not for: Expo/EAS-managed internal-testing uploads driven by your calibrated deploy targets — that's /deploy testflight-internal; non-iOS projects (it stops if no Xcode project is found)

Prerequisites

• TestFlight/App Store uploads need an App Store Connect API key. Set three environment variables before running the skill: APP_STORE_CONNECT_API_KEY_ID, APP_STORE_CONNECT_API_ISSUER_ID, and APP_STORE_CONNECT_API_KEY_PATH (path to your .p8 key file). Generate the key from your Apple Developer account under App Store Connect → Users and Access → Integrations. Without these, the skill falls back to producing a local IPA for you to upload manually.
• Manual code signing (instead of the default Xcode-managed automatic signing) needs PROVISIONING_PROFILE_SPECIFIER and CODE_SIGN_IDENTITY set as environment variables before running the skill, e.g. export PROVISIONING_PROFILE_SPECIFIER=<profile-name> and export CODE_SIGN_IDENTITY=<identity-name>.

Quickstart

/deploy-iosCopy

What you'll see: the detected workspace/project and scheme, a simulator build (the default target), then the app installed and launched in the iOS Simulator with a summary of device, OS version, and bundle ID.

Examples

/deploy-ios                                    # build + launch in the default simulator
/deploy-ios simulator --device "iPhone 16 Pro" # pick a specific simulator device
/deploy-ios testflight --scheme MyApp          # archive + upload to TestFlight
/deploy-ios appstore                           # archive + upload for App Store review
/deploy-ios simulator --clean                  # clean build when caches are suspectCopy

Arguments & flags

What it does

1. Detects the project — finds the .xcworkspace (or .xcodeproj), lists schemes, detects the package manager (SPM/CocoaPods/Carthage), warns if Pods are stale, and reads build settings for bundle ID and deployment target. If multiple schemes exist and you didn't pass --scheme, it asks which to use — a user-confirmation checkpoint. If there's no Xcode project, it stops.
2. Resolves the target — simulator (default), TestFlight, or App Store.
3. Builds — simulator builds use a Debug configuration against your chosen device; TestFlight/App Store builds clean-archive in Release with automatic code signing (manual signing supported if you provide the profile and identity — see Prerequisites above).
4. Deploys — simulator: installs and launches the app, opening Simulator.app if needed. TestFlight/App Store: exports the archive and uploads directly to App Store Connect using your App Store Connect API key (see Prerequisites); if no key is configured, it produces a local IPA and tells you to upload via Transporter or the App Store Connect web UI.
5. Validates — simulator: confirms the app installed and launched without crashing, reports device/OS/bundle/build time. Uploads: confirms success and reminds you TestFlight processing takes 15–30 minutes.

After two failed build attempts it stops, shows the full error log, and asks for guidance.

Fastlane integration

If your project has a fastlane/ directory, the skill automatically uses your existing Fastlane lanes instead of raw xcodebuild — for simulator builds, fastlane run build_app; for TestFlight, fastlane pilot upload; for App Store, fastlane release if that lane exists. Make sure your lanes support the target you're deploying to (simulator, testflight, appstore); the skill checks fastlane lanes first.

Output & artifacts

• Simulator: the app running in the Simulator, plus a build summary in the conversation
• TestFlight/App Store: an archive under build/<scheme>.xcarchive, an exported IPA, and an upload to App Store Connect (with bundle version and build number reported)
• No files committed and no remote infrastructure touched

Troubleshooting

Related

• /deploy — environment-level deploys, including EAS/fastlane internal-testing tracks from your calibrated config
• /fix — for code-level build failures the toolchain can't resolve
• /sre — health and operations for your backend services

/deploy

Deploy to local, staging, preview, and mobile testing environments. Reads deployment knowledge from /calibrate. Refuses production — those go through your team's review process.

Synopsis

/deploy [<local|staging|preview|testflight-internal|google-play-internal>] [<service>] [--dry-run]Copy

Production is refused — always. /deploy production (or any environment marked production) stops hard, explains why, and offers the safe path instead: PR → CI → review → your pipeline deploys on merge. There is no override.

When to use it

• Getting your changes onto staging or a preview URL so the team can test them
• Starting/restarting your full local stack (/deploy local)
• Pushing an iOS or Android build to internal testing (TestFlight / Play internal track)
• Not for: production releases — create a PR with /pr and let your review process ship it; pure local server restarts — /restart restarts already-running services, while /deploy local starts the full stack and runs migrations

Choosing an environment: use local for your own development, staging to share work with your team, preview for a temporary URL tied to a branch, and testflight-internal/google-play-internal to push a build to mobile internal testers.

Quickstart

/deploy stagingCopy

What you'll see: pre-deploy checks (clean tree, right branch, CI green, platform CLI authenticated), then the platform-appropriate deploy, a health check, and a plain-English summary with the staging URL.

Examples

/deploy staging                    # deploy current branch to staging
/deploy local                      # start/restart the local stack, run migrations, verify health
/deploy preview                    # temporary preview URL (Vercel/Netlify/Cloudflare style)
/deploy testflight-internal        # iOS build to TestFlight internal testers only
/deploy staging backend --dry-run  # show what would happen for one service, deploy nothingCopy

Service names are project-specific (e.g. backend, frontend, api) — use the names from your CLAUDE.md ## Local Dev Services table.

Arguments & flags

What it does

1. Reads the deployment knowledge base that /calibrate populated (environments, platforms, CI pipeline). If the project isn't calibrated, it stops and tells you to run /calibrate first.
2. Resolves the target — if you didn't name an environment, it shows a menu of your environments — a user-confirmation checkpoint.
3. Production safety gate — refuses production/prod/live unconditionally and offers staging, /pr, or /sre ci instead.
4. CI pipeline check — if your CI already deploys this environment, it offers options (trigger the pipeline, watch it, bypass CI for staging with confirmation, or explain the pipeline) — a user-confirmation checkpoint rather than deploying around your pipeline.
5. Pre-deploy checks — clean working tree, correct branch, latest CI run passing, platform CLI installed/authenticated, project linked. Failures stop the deploy with a concrete fix.
6. Deploys — spawns an SRE agent with the platform-specific sequence (Railway, Vercel, Fly.io, Netlify, Cloudflare Pages, GitHub Pages, Render, or EAS/fastlane for mobile internal tracks). local starts services, runs migrations, and verifies health.
7. Verifies and reports — health checks with retries (or build number + processing ETA for mobile), logs the deploy to the knowledge base, and presents next steps in plain English.
8. Offers auto-deploy — after a successful staging deploy, asks if you want a cloud Routine that deploys staging automatically on PR merge — a user-confirmation checkpoint (declining changes nothing).

Agents spawned

Output & artifacts

• The deployed environment's URL with health status (or TestFlight/Play build number and processing ETA)
• A deploy log entry appended to .claude/knowledge/shared/deployment.md after every deploy
• Optionally: a Monitor watcher for CI-triggered deploys, and an auto-deploy Routine if you opt in

Troubleshooting

Related

• /calibrate — required first run; builds the deployment knowledge /deploy reads
• /pr — the path to production: PR, review, merge, pipeline deploys
• /sre — deploy-check verifies deployments; ci watches the pipeline
• /deploy-ios — full Xcode-level control for iOS builds (simulator/TestFlight/App Store)

/docs

Audit and generate documentation for skills, agents, and hooks — including full per-skill customer doc pages.

Synopsis

/docs <audit|write|check> [skill-name]Copy

When to use it

• You've added a project-specific skill, agent, or hook and want its documentation written to the same standard as the toolkit's own pages
• You want a coverage report: which skills have full doc pages, which have quality drift (stale one-liners, broken links, missing sections)
• In CI or a pre-PR hook, to gate new skills on meeting the documentation bar
• Not for: writing your application's docs (READMEs, API docs for your product code) — /docs documents the toolkit surface (skills/agents/hooks), not your app

Quickstart

/docs auditCopy

What you'll see: a report listing which skills meet the full documentation bar, which are missing pages, and which have quality issues (e.g., a synopsis that drifted from the skill's actual usage string), with a next action per item.

Examples

/docs audit              # coverage + quality report, no writes
/docs write my-skill     # generate the full doc page for one skill
/docs write              # sweep mode — fix README/GETTING-STARTED mention gaps and list skills needing pages (no page generation)
/docs check              # silent pass/fail gate — exit 1 if a newly added skill lacks docsCopy

Arguments & flags

What it does

<!-- draft: review -->

1. Detects scope — in check mode, only skills/agents/hooks added in the current branch (requires the project to be git-initialized with a main branch to diff against); in audit/write mode, every user-invocable skill.
2. Checks each item against the documentation bar — a doc page exists with all required sections: Synopsis, When to use it, Quickstart, Examples, What it does, Output, Troubleshooting, and Related (defined in customer-docs/skills-page-required-sections.txt); the page's one-liner matches the skill's frontmatter description (the description text before its "Usage:" clause — anything after "Usage:" is stripped before comparing); the synopsis matches its usage string; the skill is reachable from at least one task surface (routing table, workflow guide); relative links resolve; the name is mentioned in the README and getting-started guide.
3. Audit mode — prints the report: items at full bar, items missing pages (the backfill queue), and quality issues per item. No writes.
4. Write mode with a skill name — reads the skill's SKILL.md in full (requires customer-docs/docs/skills/_TEMPLATE.md to exist) and generates the page from the template: phases become the "What it does" list, confirmation gates are marked explicitly, artifacts and troubleshooting come from the skill body. Inferred prose is marked <!-- draft: review --> for human review. It also proposes the task-surface placement — the exact routing-table row or workflow entry where the new skill should appear. You then run ./generate-docs.sh && ./generate-site.sh yourself to regenerate the reference tables and render the page on the site (verify zero WARN lines) — the skill does not run the generators for you.
5. Write mode without a name — fixes README/getting-started mention gaps and lists which skills still need pages; it deliberately does not mass-generate pages, since each page needs review.
6. Check mode — exits 0 silently when complete, exits 1 with the gap list when a new skill is below the bar (used by the pre-PR docs hook and CI).

Output & artifacts

<!-- draft: review -->

• Audit/check report in the conversation (check mode also sets the exit code for CI)
• Write mode: a new per-skill doc page with all required sections, plus a proposed task-surface placement. Run ./generate-docs.sh && ./generate-site.sh afterward to regenerate the reference tables/site so the page is linked — the skill itself does not run these generators.
• README and getting-started mention entries where missing

Troubleshooting

Related

• /calibrate — creates the project-specific skills and agents you'll want documented
• /scan — populates CLAUDE.md project context; /docs covers the toolkit surface
• /pr — the pre-PR docs check runs as part of shipping a new skill

/engagement-tracker

Track consulting engagement progress and milestones.

Synopsis

/engagement-tracker <client-name> <--action status|update|milestone>Copy

When to use it

• Checking where an engagement stands — progress bars, RAG status, blockers, next actions
• Logging a dated progress update after a working session or client call
• Marking a milestone complete and rolling phase progress forward
• Not for: producing the client-facing status report document — that's /deliverable-builder with --type status-update

What is RAG? RAG (Red/Amber/Green status indicator) tracks engagement health across five dimensions: schedule, scope, resources, quality, and stakeholder. Each dimension rates as Red (blocked/at risk), Amber (issues in progress), or Green (on track). The overall engagement RAG is the worst status across all dimensions.

Quickstart

/engagement-tracker acme-corpCopy

What you'll see: an ASCII dashboard — per-phase progress bars and milestone checklists, overall progress, key metrics (days elapsed, on-track yes/no), a RAG summary across schedule/scope/resources/quality/stakeholder, blockers, and next actions — also written to tracking/status.md.

Examples

/engagement-tracker acme-corp                       # default action: status dashboard
/engagement-tracker acme-corp --action status       # same, explicit
/engagement-tracker acme-corp --action update       # add a dated progress log entry
/engagement-tracker acme-corp --action milestone    # mark a milestone complete (e.g. "D3")Copy

Arguments & flags

What it does

1. Loads engagement state — reads clients/<client-name>/engagement.json. On first run it creates the file with four tracked phases (Discovery & Assessment, Analysis & Strategy, Solution Design, Deliverable Creation), each with predefined milestones (locked phase structure; you cannot create custom phases or milestones, but you can edit milestone names in engagement.json directly if needed). User-confirmation checkpoint: when creating fresh, it prompts you for the start date and target end date.
2. status — renders the full ASCII dashboard: progress bars per phase, milestone checklists with completion dates, overall progress, key metrics computed from the dates (time used %, on-track), the five-dimension RAG summary (overall RAG = worst dimension), blockers and risks, next actions, and recent updates. Written to tracking/status.md and shown in the terminal. Important: RAG ratings default to GREEN — you must update them with justifications during status updates to avoid all-green dashboards.
3. update — user-confirmation checkpoint: prompts for the update details (or accepts them in the invocation), then appends a dated entry — activities completed, decisions, risks/issues, next steps — to tracking/updates.md, updates engagement.json (next actions, blockers, RAG ratings with justifications, phase progress), and regenerates the dashboard.
4. milestone — displays the current milestone list with IDs, prompts you for the milestone ID to mark complete (or accepts it as a parameter), updates the milestone and recalculated phase progress in engagement.json, appends a completion entry to tracking/milestones.md, shows a confirmation box, and regenerates the dashboard. When all milestones in a phase complete, the phase automatically closes and advances to the next phase — you will see a notification confirming which phase is now active.

Updates and milestone entries are always appended — previous entries are never overwritten.

Output & artifacts

All under clients/<client-name>/:

• engagement.json — engagement state: phases, milestones, RAG, blockers, next actions, update log
• tracking/status.md — the ASCII dashboard (regenerated after every action)
• tracking/updates.md — append-only dated progress log
• tracking/milestones.md — append-only milestone completion records

Troubleshooting

Related

• /consulting — the engagement orchestrator; runs this as the track phase
• /deliverable-builder — turns this tracking data into a client-facing status update
• /client-discovery — kicks off the first tracked phase of the engagement

/explore

Fast codebase exploration using Haiku. Use for finding files, searching code, understanding structure.

Synopsis

/explore <query>Copy

When to use it

• "Where is X?" questions — finding files, functions, classes, or patterns
• Understanding directory structure or how a subsystem is organized, cheaply
• Scouting before expensive work — many toolkit skills run the same explore-light agent internally for exactly this reason
• Not for: deep architectural reasoning or debugging novel problems — exploration findings feed those tasks, they don't replace them; and not for making changes — /explore only reads

Quickstart

/explore how does authentication workCopy

What you'll see: the explore-light agent (running on Haiku, ~60x cheaper than Opus) scans the codebase and returns a concise summary with the relevant file paths — without burning your main session's context on the search itself.

Examples

/explore find all API route handlers          # pattern search across the codebase
/explore how does authentication work         # understand a subsystem
/explore where is the database schema defined # locate a specific definitionCopy

What it does

1. Parses your query from the skill arguments.
2. Spawns the explore-light agent (Haiku) with your query as its prompt — the agent does the file finding, grepping, and structure summarizing in its own context.
3. Returns the findings — file paths and a brief explanation — back into your session.

Agents spawned

Output & artifacts

• Findings in the conversation: file paths, brief descriptions, and structural summaries
• No files written, no code modified — read-only by design

Troubleshooting

Related

• /onboard — session briefing that includes project orientation
• /scan — persists project structure into CLAUDE.md, rather than answering one-off queries
• /calibrate — deep project learning; /explore is the lightweight everyday counterpart

/extensions disable

Disable a previously enabled compliance extension pack.

Synopsis

/extensions disable <pack_id> [reason]Copy

When to use it

• A pack no longer applies to this project (out of scope, requirements changed)
• Temporarily pausing a pack you plan to re-enable under a different scope
• Not for: skipping a single rule while keeping the rest of the pack active — use /extensions waive instead. Use disable when the whole pack no longer applies; use waive when only one rule in it doesn't.

pack_id must be the full domain/name form shown by /extensions list (e.g. compliance/hipaa) — a bare name like hipaa won't match.

Quickstart

/extensions disable compliance/hipaa "Out of scope for this project"Copy

What you'll see:

Archived evidence to .claude/extensions/compliance-hipaa/archive/2026-07-05T00-00-00Z/   (only if a report existed)
Disabled compliance/hipaa (reason: Out of scope for this project).
To re-enable: /extensions enable compliance/hipaaCopy

The pack's rules stop contributing to skill prompts, its current evidence report is archived (if one existed), and the audit trail is preserved.

Examples

/extensions disable compliance/hipaa "Out of scope for this project"   # disable with inline reason
/extensions disable security/baseline                                  # no reason given — you'll be asked for oneCopy

What it does

1. Collects a reason — if you didn't supply one, prompts you with a dropdown menu of common reasons (e.g. "Out of scope for this project"), plus a free-text and a cancel option. This is a user-confirmation checkpoint: a reason is required for the audit trail, and you can cancel out of it.
2. Validates the pack is currently enabled — disabling a pack that isn't enabled (or is already disabled) exits cleanly (idempotent).
3. Marks the entry disabled in .claude/extensions/.enabled.json with timestamp and reason — the original entry is updated, never deleted, so a later re-enable keeps the full history.
4. Archives the evidence report (if one exists) to .claude/extensions/<pack-kebab>/archive/<timestamp>/.
5. Confirms, printing Disabled {pack_id} (reason: {reason}). followed by To re-enable: /extensions enable {pack_id} — re-enabling regenerates evidence from scratch.

Output & artifacts

• Updated .claude/extensions/.enabled.json — entry marked with disabled_at and disabled_reason
• .claude/extensions/<pack-kebab>/archive/<timestamp>/evidence-report.md — archived evidence (when one existed)

Troubleshooting

Related

• /extensions enable — re-enable later; the prior disable is preserved in the audit trail
• /extensions list — all packs on disk, enabled or not
• /extensions status — operational detail for enabled packs
• /extensions waive — narrower alternative: waive one rule, keep the pack

/extensions enable

Enable a compliance extension pack for this project.

Synopsis

/extensions enable <domain>/<name>Copy

The pack_id argument must be in <domain>/<name> format (e.g., compliance/hipaa, security/baseline).

When to use it

• Opting a project into a compliance or quality pack (e.g. compliance/hipaa, security/baseline) so its rules apply to toolkit workflows
• Re-enabling a pack you previously disabled — both entries (the original disable and the new re-enable) are kept in the audit trail with timestamps, so you can see when it was disabled and when it was re-enabled
• Not for: seeing what's available — that's /extensions list; or skipping one rule in an enabled pack — that's /extensions waive

Quickstart

/extensions enable compliance/hipaaCopy

What you'll see: Enabled compliance/hipaa v1.0.0 (restrictiveness 5, source original). Evidence will be generated on next /pr run. — plus a conflict count if the pack's rules overlap with already-enabled packs.

Examples

/extensions enable compliance/hipaa      # opt in to a pack (format: <domain>/<name>)
/extensions enable security/baseline     # enable a second pack — conflicts auto-resolveCopy

What it does

1. Validates the pack exists on disk (both its opt-in and rules files) and has well-formed frontmatter.
2. Checks current state — already-active packs exit cleanly (idempotent); a previously disabled pack is detected as a re-enable and the prior audit trail is preserved.
3. Scans for rule conflicts with already-enabled packs. Overlapping rules auto-resolve in favor of the higher restrictiveness (alphabetical pack ID on a tie) — each resolution is logged, with no interactive prompt.
4. Records the enablement in .claude/extensions/.enabled.json with the pack ID, version, timestamp, your git email, and a source field (always "manual" for this command). Re-enables also add a re_enabled_at timestamp.
5. Confirms — evidence for the pack is generated on your next /pr run.

Output & artifacts

• .claude/extensions/.enabled.json — the project's enabled-pack and waiver registry. Example entry: A re-enable adds "re_enabled_at": "<iso8601>" to the new entry while leaving the prior disabled entry untouched.

  {
   "pack_id": "compliance/hipaa",
   "version": "1.0.0",
   "enabled_at": "2026-07-05T12:00:00Z",
   "enabled_by_email": "user@example.com",
   "source": "manual"
  }Copy

• .claude/extensions/<pack-kebab>/conflict-log.md — one line per auto-resolved rule conflict
• Evidence report generated on the next /pr run

Troubleshooting

Related

• /extensions list — see all packs and their status
• /extensions status — enabled packs with evidence freshness
• /extensions disable — opt back out
• /extensions waive — waive a single rule instead of the whole pack
• /pr — generates the evidence report for enabled packs

/extensions list

List compliance extension packs and their status.

Synopsis

/extensions listCopy

When to use it

• Discovering which compliance/quality packs are installed and which are enabled in this project
• Looking up a pack_id before running /extensions enable
• Not for: evidence freshness and waiver detail on enabled packs — that's /extensions status

Quickstart

/extensions listCopy

What you'll see: a table of every pack on disk with its status, version, restrictiveness, source, and enable date — followed by a totals footer like 4 packs available · 2 enabled · 0 waivers active.

Examples

/extensions list    # the one and only form — no argumentsCopy

What it does

1. Resolves the extension root — project extensions/, the plugin install (if present), or the compiled bundle install at .claude/extensions-installed/, in that order.
2. Enumerates packs on disk (organized as <domain>/<name>) and reads each pack's version, source, and restrictiveness.
3. Cross-references the project's .claude/extensions/.enabled.json to mark each pack enabled or disabled. If the file doesn't exist, all packs show as disabled — that just means nothing is opted in yet.
4. Prints the table and a one-line footer with totals (packs available, enabled, active waivers).

Output & artifacts

• A status table in the conversation — nothing is written to disk
• Example row: compliance/hipaa disabled 1.0.0 5 original —

Troubleshooting

Related

• /extensions enable — opt in to a pack from this list
• /extensions status — enabled packs only, with evidence freshness and waivers
• /extensions disable — opt back out
• /extensions waive — waive a single rule with a rationale

/extensions status

Print enabled extension packs with evidence freshness and waiver counts.

Synopsis

/extensions statusCopy

When to use it

• Checking compliance health before a release: is every enabled pack's evidence current?
• Auditing how many waivers are active and which packs had rule conflicts
• Not for: browsing all packs on disk including disabled ones — that's /extensions list

Quickstart

/extensions statusCopy

What you'll see: a health line (✓ All evidence current. or a ⚠ warning), then a per-pack table with version, enable date, evidence report age, waiver count, and conflict-log entries. Conflicts are rule clashes between two enabled packs that were auto-resolved by /extensions enable (the higher-restrictiveness rule wins) — the count here just reflects how many such resolutions are on record for that pack; see its conflict-log.md if you want the detail.

Examples

/extensions status    # the one and only form — no argumentsCopy

What it does

1. Reads the project's .claude/extensions/.enabled.json; if nothing is enabled, points you to /extensions list and /extensions enable.
2. For each active pack, gathers operational detail: when it was enabled, when its evidence report was last regenerated (or (never)), how many waivers target it, and whether a conflict log exists.
3. Prints a health line first — flags packs whose evidence is missing or older than the latest commit on the current branch (⚠ N packs have stale or missing evidence — run /pr to regenerate.), otherwise confirms all evidence is current. Evidence reports are the compliance-rule-check output for a pack, generated when you run /pr; if a report is missing or older than your latest commit, that pack's compliance status may not reflect your current code — that's what "stale" means here.
4. Prints the status table with one row per enabled pack.

Output & artifacts

• A health line and status table in the conversation — nothing is written to disk
• Stale evidence is regenerated by your next /pr run

Troubleshooting

Related

• /extensions list — all packs on disk, including disabled ones
• /extensions enable / /extensions disable — change what's active
• /extensions waive — the waivers counted in this view
• /pr — regenerates the evidence reports this command checks

/extensions waive

Waive a specific extension rule with a written rationale.

Synopsis

/extensions waive <domain>/<name>/<RULE-ID> "reason"Copy

When to use it

• An enabled pack's rule genuinely doesn't apply to this project, and you want the code reviewer to stop flagging it as blocking
• Overriding the most-restrictive auto-resolution when two packs conflicted and the winning rule is wrong for your context
• Not for: turning off an entire pack — that's /extensions disable

Prerequisite: the pack must already be enabled — run /extensions enable <pack_id> first if it isn't.

Quickstart

/extensions waive compliance/hipaa/HIPAA-312b "No PHI is stored in this service"Copy

What you'll see:

Waived compliance/hipaa/HIPAA-312b — "No PHI is stored in this service."
This rule will appear as 'waived' in the next evidence report.
To revoke: edit .claude/extensions/.enabled.json and remove the entry from .waivers[].Copy

The rule shows as waived (with your rationale) in the next evidence report instead of being enforced as blocking.

Examples

/extensions waive compliance/hipaa/HIPAA-312b "No PHI is stored in this service"   # waive one rule with a rationale
/extensions waive security/baseline/SEC-04 "Covered by org-level WAF policy"       # format: <domain>/<name>/<RULE-ID>Copy

What it does

1. Parses the target — the first two path segments are the pack ID, the remainder is the rule ID. A quoted reason is required.
2. Validates that the pack is currently enabled and that the rule ID actually exists in the pack's rule file.
3. Checks for duplicates — waiving an already-waived rule exits cleanly, showing the existing reason (idempotent).
4. Appends the waiver to .claude/extensions/.enabled.json with the rule, reason, timestamp, and your git email.
5. Confirms — the rule renders as waived with your rationale in the next evidence report, and the code reviewer no longer treats it as blocking for this project.

To revoke a waiver, edit .claude/extensions/.enabled.json and remove the entry from .waivers[].

Output & artifacts

• A waiver entry in .claude/extensions/.enabled.json (.waivers[])
• The rule appears as waived with your reason in the pack's evidence report on the next /pr run

Troubleshooting

Related

• /extensions enable — the pack must be enabled before its rules can be waived
• /extensions disable — the whole-pack alternative
• /extensions status — shows active waiver counts per pack
• /extensions list — pack inventory and totals
• /pr — generates the evidence report where waivers appear

/fix

Formal bug fix pipeline — root cause analysis, scope lock, behavior contract, differential testing, regression proof.

Synopsis

/fix <description|#issue> [--severity critical|high|medium|low] [--hotfix|--lite|--lite-strict|--verified|--full|--swarm]Copy

When to use it

• A real bug: wrong output, exception, regression, "this used to work" — anything where the cause needs proving before the fix
• Production fires — --hotfix compresses the pipeline without skipping correctness checks
• Not for: building features — that's /planning then /implement; or a red CI pipeline — that's /ci-fix

Note: /fix can also be auto-triggered by a Monitor webhook when production error events cross a threshold — see Monitor Integration in the skill for the .claude/monitors/ config that wires an error tracker (Sentry, Datadog, Rollbar) to the pipeline.

Quickstart

/fix POST /auth/refresh returns 500Copy

What you'll see: an investigation that converges on a root cause (with file:line evidence), a scope-locked fix with a regression test proven to catch the bug, a differential test showing nothing else changed (any unrelated test regression blocks the PR), and a PR with the full evidence trail.

Examples

/fix #123                                      # load the bug from a GitHub issue
/fix #123 --severity critical                  # explicit severity (otherwise auto-assessed)
/fix #123 --hotfix                             # production fire — expedited single-trace path
/fix --severity high token refresh fails silentlyCopy

Arguments & flags

All six investigation-depth flags (--hotfix, --lite, --lite-strict, --verified, --full/--swarm) are mutually exclusive — pass at most one. Leave them all off to let auto-detection pick a depth from the bug's signals.

What it does

User-confirmation checkpoints (marked below) are interactive prompts where /fix pauses and asks you to decide something — which hypothesis to pursue, whether to accept a symptom-side fix, what QA level to run. In CI, autopilot, or Monitor-triggered runs, each checkpoint uses a safe default instead of blocking.

1. Loads bug context — from the issue or description, syncs with the default branch (refuses to run with uncommitted changes), runs an advisory revert-check so a buffered revert can't masquerade as the bug, and checks the knowledge base for similar past incidents. If invoked with no description, it asks for one first (user-confirmation checkpoint).
2. Root cause investigation — competing investigator agents trace the bug independently, then cross-challenge each other until they converge on a causation chain (symptom → root) with cited evidence. Depth is auto-selected: lite for smoking-gun tracebacks, full swarm for auth/payments/migrations/security, verified (analyst + challenger) as the default when neither signal fires. If the swarm can't converge, you choose which hypothesis to pursue (user-confirmation checkpoint). If a lite investigation finishes with low confidence, disagreeing agents, or both agents stopping at the symptom with no root-cause walk-back, it auto-escalates to a full investigation — pass --lite-strict to disable this and accept the lite verdict as-is.
3. Scope lock — builds the dependency graph from the root cause and writes a Fix Zone (may modify), Watch Zone (caution), and Frozen Zone (blocked). The fix cannot touch files outside the zone.
4. Behavior contract — tables what MUST change and what MUST NOT change, with a baseline test-suite snapshot.
5. Implements the fix — a scoped agent fixes at the root cause (not the symptom) and writes a regression test, which is mutation-checked: it must FAIL with the fix reverted and PASS with it applied.
6. Review swarm — a fix-reviewer (7-point correctness checklist plus a root-cause pre-gate) and a qa-attacker (3-5 attack scenarios) review in parallel and cross-examine. The pre-gate verifies the diff actually lands at or upstream of the root cause, not just at the symptom, and returns PASS / FAIL / SYMPTOM-ONLY-JUSTIFIED. A symptom-only fix (FAIL) is BLOCKED and sent back to implementation; a justified symptom-side fix (SYMPTOM-ONLY-JUSTIFIED) is surfaced to you for confirmation (user-confirmation checkpoint) in interactive mode, or logged as a warning-only in CI/autopilot.
7. Differential testing — re-runs the full suite and diffs against the baseline. Any unrelated PASS→FAIL blocks the PR.
8. Post-fix handoff — asks what QA level to run before PR: commit / full / skip, with full recommended for critical/high severity (user-confirmation checkpoint), runs /qa, restarts local servers, and asks you to test the fix manually before proceeding (user-confirmation checkpoint). Then creates the PR via /pr with the bug-fix evidence template, updates the knowledge base, runs a final completion verification, and prints a post-fix checklist (incident record, bug-pattern, knowledge-graph write, verifier) before announcing the PR URL. In unattended runs (CI, autopilot, Monitor-triggered) it never prompts: the QA level is derived from severity and manual testing is deferred with a logged notice.

Agents spawned

Note: in calibrated projects, these agent assignments and model tiers can be overridden — check .claude/registry.json for active agent substitutions and model-policy.yml (or .claude/model-policy.yml) for model-tier overrides.

Output & artifacts

• .claude/.fix-scope-lock.json — the enforced Fix/Watch/Frozen zones. Written in Step 2 and read by the implementation agent, which is blocked from editing anything outside the Fix Zone. Don't delete or hand-edit it mid-fix — if the scope is too narrow, re-run /fix with a clearer description instead.
• .claude/.fix-behavior-contract.md — what changes vs. what's preserved
• A regression test in your test suite, proven to catch this specific bug
• A PR with root cause, scope, behavior contract, and test evidence; incident record in .claude/qa-knowledge/incidents/ and a bug-patterns.md entry

Troubleshooting

Related

• /qa — the QA pass /fix runs before creating the PR
• /ci-fix — for CI/deploy failures rather than code bugs
• /incident — triage first when you don't yet know if it's a bug, infra, or CI problem
• /review-pr — bug-fix-aware PR review after the fix lands

/goal

Speed-first goal-oriented loop — set an objective, agent picks next concrete action, captures evidence, stops at PR. Different from /autopilot (rigor-first multi-issue queue).

Synopsis

/goal <objective> | pause | resume | clear | statusCopy

When to use it

• The destination is clear but the path is not — "cut the homepage LCP under 2s", "get CI under 5 minutes"
• One freeform objective you want driven autonomously with evidence at every step
• Not for: working through a backlog of issues — that's /autopilot, the rigor-first multi-issue queue with P0–P5 ranking and risk classification; /goal is single-objective and speed-first
• Not for: a well-defined feature (/planning → /implement) or a specific bug (/fix)

Quickstart

/goal Cut homepage LCP below 2s on mobileCopy

What you'll see: a knowledge-base read and quick scout, a short block of clarifying questions, then a plan (requirements + subtasks) for you to confirm. After that the loop self-paces — one concrete action per turn, each verified and logged as evidence — and stops when the goal is ready for PR.

Examples

/goal Cut homepage LCP below 2s on mobile   # set an objective and start the loop
/goal status                                # current goal, subtasks done, evidence, next action
/goal pause                                 # pause — state preserved
/goal resume                                # pick up where it left off
/goal clear                                 # discard the active goal (archived, not deleted)Copy

Arguments & flags

What it does

1. Scout — first checks for an already-active goal — user-confirmation checkpoint: if one exists (status clarifying/proposed/active/paused/awaiting_pr), it asks "replace / keep / cancel" and waits for you. Otherwise it reads the project knowledge base first (profile, conventions, domain rules, past goals, known footguns) — mandatory, and calibrates the whole goal — then a cheap explore-light scan fills only the gaps.
2. Clarify — user-confirmation checkpoint: presents what it already knows, 3–5 context-aware questions with concrete options and defaults, and its assumptions. Answer them, or say "go" to accept all defaults.
3. Confirm plan — user-confirmation checkpoint: shows the approach, requirements (each with an evidence type), and subtasks (each with a done_when clause). Nothing executes until you approve; a dry-run option executes without writes.
4. Loop — each turn picks ONE concrete action (read, edit, test run, or a Sonnet agent spawn for non-trivial code), executes it, and appends evidence. A Stop hook auto-continues the loop so you don't have to type "continue". For large goals the loop becomes an orchestrator: it decomposes the plan into file-disjoint lanes, runs each in its own git worktree via parallel Sonnet subagents (dynamic workflows when available), routes subtasks to installed toolkit skills first, monitors agents with a takeover clock (stalled or over-time lanes get one stand-down order, then the orchestrator finishes them itself), and independently re-runs each agent's claimed verification before accepting it.
5. Verify — non-negotiable — verification is mandatory and blocking: every code change must be verified (lint, types, tests) in the same turn before the subtask can be marked done or the loop advances. If the changed code has no tests, they're written first, then run. Every evidence entry carries a verified boolean, and goal completion (the Phase 6 PR) is blocked if any evidence entry is still verified: false.
6. PR — hard stop — when all subtasks are done and requirements satisfied, it presents the summary with a suggested PR title and branch and stops for you. It never creates or merges the PR on its own unless you passed --merge-on-green; run /pr or tell it to.
7. Escalation — the loop comes back to you instead of spinning, on any of: the same failure surviving 2 distinct fix theories, the same subtask stuck 4+ turns without a verified deliverable, CI red on main after a merge (fix-forward once, then escalate on the second failure), anything destructive/irreversible beyond the repo, a data-loss discovery, an architecture fork that changes the goal's shape, or the spawn/cost budget being exceeded. Each arrives as "what broke / why / what was tried / 2–3 options with a recommendation". You also get scoreboard updates on every merge and an ETA on request or whenever the critical path changes.
8. Learnings — on completion, archives the goal state and appends lessons to the project knowledge base for future runs, plus a final report: requirement → evidence table, everything shipped, and explicitly-listed loose ends.

Agents spawned

QA passes aren't a spawned agent — they route to the installed /qa skill like other toolkit skills the plan needs.

Output & artifacts

• .claude/.goals/current.json — full goal state: clarifications, subtasks, evidence log, turns, connections
• .claude/.goals/archive/ — completed/cleared goals
• Code changes on a feature branch (auto-named goal/<slug> if needed) — never pushed to main
• Lessons appended to .claude/knowledge/shared/goals-history.md and related knowledge files

Troubleshooting

Related

• /autopilot — the "drain the queue" tool; /goal is the "find the path" tool
• /planning + /implement — for well-defined features with known scope
• /fix — formal pipeline for a specific bug
• /pr — create the PR when the goal reaches its hard stop

/implement

Spin up an implementation team from a plan.

Synopsis

/implement <feature-name> [--frontend-only] [--backend-only] [--no-redteam] [--redteam-once] [--redteam-once-strict] [--redteam-strict] [--tasks] [--resume-from] [--phase] [--phases] [--all-phases] [--workflow|--classic]Copy

When to use it

• A plan exists at .claude/plans/<feature-name>.md (from /implementation-plan) and you're ready to build
• You want backend, frontend, and QA agents working the plan in parallel, with an optional red team challenging the code
• Not for: writing the plan — that's /implementation-plan; or one-off bug fixes — that's /fix

Running in CI/autopilot: when CLAUDE_AUTOPILOT=1 or CI=true, the mode prompt is skipped and you must pass the feature name plus an explicit red-team flag (--no-redteam, --redteam-once, or --redteam-strict) on the command line — otherwise the run exits with a missing-args error.

Quickstart

/implement dark-modeCopy

What you'll see: a mode prompt (Auto / Guarded / Fast / Strict), then a team builds the plan's tasks, red team findings get challenged and fixed, QA runs at the level you pick, and the flow ends with an open PR.

Examples

/implement dark-mode                       # full team per the plan's layers, mode prompt
/implement fix-component --frontend-only   # frontend + qa only, no backend agent
/implement add-api --backend-only          # backend + qa only
/implement dark-mode --no-redteam          # Fast mode — build only, skip red team
/implement dark-mode --redteam-once        # Guarded — one red-team pass at the end
/implement dark-mode --redteam-strict      # block on any unresolved HIGH finding
/implement big-feature --phase 2           # multi-phase plan: run only phase 2
/implement big-feature --phases 2-4        # run a contiguous phase range
/implement big-feature --all-phases        # run all remaining phases sequentiallyCopy

Arguments & flags

What it does

1. Plan resolution — if no feature name was given, a picker lists available plans (user-confirmation checkpoint). Loads the plan and the matching PRD spec (user stories + edge cases) for traceability.
2. Phase detection — multi-phase plans get per-phase state tracking in .claude/plans/<name>.state.json. If the plan changed since the last run, a phase was interrupted, or all phases are complete, the skill asks how to proceed (user-confirmation checkpoint).
3. Mode selection — unless a red-team flag was passed, asks Auto / Guarded / Fast / Strict (user-confirmation checkpoint). Auto picks from plan size and risk keywords (auth, payments, data migration, security, PII → Strict): fewer than 3 tasks and fewer than 5 files → Fast; fewer than 3 tasks with 5+ files → Guarded; 3-9 tasks with no risk keywords → Guarded; 10+ tasks or any risk keyword present → Strict.
4. Context gathering — explore-light scans existing code patterns; topic wikis and the knowledge base are consulted so agents match the project instead of inventing patterns.
5. Spawns the team in parallel — backend and/or frontend per the plan's layers, plus QA. Backend shares the API contract with frontend before either implements; QA traces every user story and edge case to code.
6. Red team — red-challenger generates attack scenarios against the diff; red-reviewer checks plan compliance (no scope creep, no gaps). Developers must answer each finding FIXED / DEFENDED / ACKNOWLEDGED. Unresolved CRITICALs block — user-confirmation checkpoint: fix / override / abort. Max 2 cycles.
7. Phase loop (multi-phase only) — in one-phase-at-a-time mode, pauses between phases and asks whether to proceed (user-confirmation checkpoint); failed phases prompt retry / skip / stop.
8. Post-implementation workflow — asks what QA level to run (commit / full / staging / skip — user-confirmation checkpoint), runs /qa, restarts local servers and waits for your manual test sign-off (user-confirmation checkpoint: ready / issues), then creates the PR via /pr --skip-qa and asks what's next.

With --workflow, the red-team finding generation in step 6 runs as a 2-task dynamic Workflow that returns structured findings (severity, file, line) instead of free-text reports — the challenge-defend cycle, verdict gate, escalation rules, and cycle cap are identical either way, and any Workflow failure falls back to classic automatically. Classic is the default until the workflow path is validated.

Agents spawned

Output & artifacts

• Code changes in your working tree, scoped to the plan's backend/frontend directories
• .claude/plans/<feature-name>.state.json — phase status (multi-phase plans only)
• An implementation report (files changed, red team summary), QA results, and a GitHub PR opened via /pr --skip-qa

Troubleshooting

Related

• /implementation-plan — produces the plan this skill consumes
• /qa — the QA levels offered after the build
• /pr — the PR step this skill chains into
• Workflow guide

/implementation-plan

Spin up an adversarial planning team for a feature whose PRD already exists. Reads .claude/specs/<feature>.md, runs the PM + Architect (+ Devil's Advocate) debate, and writes a locked-scope plan to .claude/plans/<feature>.md.

Synopsis

/implementation-plan <feature-name> [--design] [--gtm] [--fast] [--lite] [--lite-strict] [--sync]Copy

When to use it

• After you've reviewed (and edited, if needed) the PRD that /planning produced
• You want scope locked and a task breakdown debated before any code is written
• Not for: drafting the PRD itself — that's /planning; or building — that's /implement

Non-interactive mode (CI/Autopilot)

If the environment has CLAUDE_AUTOPILOT=1 or CI=true set, the skill runs non-interactively and will not prompt you. In that mode:

• feature-name is required
• One mode flag is required: --fast, --lite, or omit it for Full mode

If a required argument is missing, the skill prints an error and exits non-zero instead of asking. If running this from a script or CI pipeline, pass the mode flag explicitly rather than relying on the interactive debate-depth prompt.

Quickstart

/implementation-plan dark-modeCopy

What you'll see: a debate-depth prompt (Auto / Fast / Lite / Full), then the PM + Architect (+ Devil's Advocate) debate runs, and a locked-scope plan lands at .claude/plans/dark-mode.md with must-haves, exclusions, cost estimates, and a task breakdown.

Examples

/implementation-plan dark-mode              # full mode by default — 2 debate rounds
/implementation-plan dark-mode --fast       # PM + Architect only, 1 round — quick iterations
/implementation-plan dark-mode --lite       # adds Devil's Advocate, 1 combined round
/implementation-plan checkout --design      # adds Design Thinker + Design Critic to the debate
/implementation-plan checkout --gtm         # adds GTM Expert for launch positioning
/implementation-plan dark-mode --sync       # append new PRD items to an existing planCopy

The task breakdown in the plan is automatically phased (organized into ### Phase N sections) when tasks have natural sequential dependencies — Lite and Full mode only. Fast mode always produces a single-phase, flat breakdown for speed.

Arguments & flags

No mode flag = Full mode (two debate rounds: scope, then feasibility).

What it does

1. Verifies the PRD exists at .claude/specs/<feature-name>.md — errors out otherwise (it never auto-runs /planning). If the PRD's feasibility is RED, it pauses — user-confirmation checkpoint: continue anyway, cancel, or open the PRD.
2. Interactive resolution — asks for debate depth (Auto recommended — picks Fast/Lite/Full from PRD signals) and optional experts via AskUserQuestion (user-confirmation checkpoint; every question includes Cancel).
3. Context gathering — explore-light codebase scan plus topic wikis and the project knowledge graph/base.
4. Spawns the debate team in parallel — PM, Architect, Devil's Advocate (unless --fast), plus design/GTM experts if flagged.
5. Structured debate — Round 1 (scope): PM claims must-haves traced to user stories, Architect counters on feasibility, DA attacks for scope creep and hidden assumptions, then a verdict. Round 2 (feasibility, Full mode): Architect leads with API contract, DB changes, and task estimates; PM and DA challenge. The PRD is authoritative — stories are not relitigated.
6. Escalation protocol — user-confirmation checkpoint: before any PRD-traced item is deferred or rejected, you're shown the team's reasoning and asked to keep it, accept the recommendation, or reduce scope. Your overrides are recorded in the plan and the DA may not re-challenge them.
7. Scope lock + plan write — locked must-haves are hashed (scope_hash) and the full plan (scope lock, technical approach, cost estimates, debate record, task breakdown, acceptance criteria) is written to .claude/plans/<feature-name>.md.
8. Completion verification + handoff — a completion-verifier agent checks the plan against the PRD, then in guided mode the skill asks before proceeding to /implement (user-confirmation checkpoint).

Agents spawned

Output & artifacts

• .claude/plans/<feature-name>.md — the locked-scope plan, with frontmatter (debate_mode, scope_hash, spec_hash, da_confidence, layers)
• Escalation log and debate record inside the plan (what was deferred, rejected, or user-overridden)
• Architecture decisions written back to .claude/knowledge/shared/ and the knowledge graph

Design spec handling: If the PRD references a design spec (a companion HTML file from /planning) and it has gone stale — meaning the PRD was edited after the design spec was generated — the plan displays a warning: ⚠ Design spec is stale (prd_hash mismatch). Run /planning <feature> --design-spec-only to regenerate. This is a normal built-in check, not an error — the plan itself is still valid, but the design reference may be out of sync with the current PRD.

Cost comparison by mode:

Troubleshooting

Related

• /planning — phase 1: produces the PRD this skill consumes
• /implement — phase 3: builds from the plan this skill writes
• Workflow guide — the full planning → implement → PR flow

Session management after planning

By the time /implementation-plan finishes, the context window is heavy with debate output, the full PRD, and codebase-scan results. Before running /implement:

• Best practice: start a fresh session — /clear, then open with a one-line brief: "Implement <feature-name> — plan at .claude/plans/<feature-name>.md". This gives /implement a clean window and avoids context rot during the build.
• Staying in this session? Run /compact focus on <feature-name> plan — planning done, ready to implement first, so the summary preserves what the build needs.
• If a debate round produced a bad result, rewind (Esc Esc) to before that round and re-prompt with a correction rather than stacking fixes on a bad output.

/incident

Incident triage orchestrator — classifies severity, diagnoses in parallel, routes to /sre, /ci-fix, or /fix based on evidence.

Synopsis

/incident [description]Copy

When to use it

• Anything is broken and you don't know which skill to use — "the site is down", "CI is failing", "users are getting timeouts"
• A production error, failed deploy, slow database, or alert firing
• Not for: a bug where you've already run the 4 diagnostic checks (health, deploys, CI, logs) and ruled out alternatives — go straight to /fix; a known CI failure — /ci-fix; routine health checks — /sre

Prerequisites: a git repository (for git log), the GitHub CLI gh (for CI/deploy status), and health endpoints defined in CLAUDE.md's Environments table. Docker is optional but used for container health checks if running. Richer diagnostics — DB queries, error rates, APM traces — require MCP servers (Sentry, Datadog, Postgres, Redis, etc.), which /calibrate can install for you.

Quickstart

/incident "500 errors on the checkout page"Copy

What you'll see: an instant severity/type classification, four parallel diagnostic checks completing in under a minute, a correlated diagnosis with confidence score, then automatic routing to the right resolution skill — ending with a verified fix and an incident report.

Examples

/incident "the site is down"      # free-text description — full triage
/incident #234                    # load the incident from a GitHub issue
/incident                         # no args — auto-detect: checks health, CI, recent deploysCopy

What it does

1. Classify (instant) — pattern-matches the description into severity (CRITICAL/HIGH/MEDIUM/LOW) and type (infra, CI, code bug, performance, local ops, data, auth). CRITICAL proceeds with no questions; HIGH/MEDIUM briefly confirm the description; LOW asks whether you want full triage or a quick check — a user-confirmation checkpoint.
2. Parallel diagnosis (< 60s) — spawns 4 cheap agents at once: health endpoints, recent deploys + CI, error signals/logs, and a knowledge-base lookup for similar past incidents. The lookup checks the knowledge graph first for ranked results (ranked by usefulness), then falls back to (or supplements with) manual search over .claude/qa-knowledge/ and .claude/knowledge/ files.
3. Correlate — combines the four signals through a decision matrix into a root-cause hypothesis with a preliminary confidence level.
4. Challenge — unless the incident is CRITICAL with high confidence, one or two Haiku devil's-advocate agents adversarially test the diagnosis. 30–120 seconds of verification here prevents 30+ minutes of chasing the wrong root cause: CRITICAL (medium/low confidence) gets a 30s fast check, HIGH/MEDIUM get a 90s full challenge, LOW gets 120s. Saying "just fix it" at any point skips the challenge.
5. Verdict gate — computes a confidence score. High score proceeds; mid-range merges the challenger's insights; low score presents the competing hypotheses and asks you to pick a path — a user-confirmation checkpoint.
6. Route to resolution — invokes the right skill automatically with all gathered evidence: /sre debug (infra/perf/data), /ci-fix (CI), /fix (code bugs), /restart (local ops). Escalations between skills are automatic.
7. Verify, report, learn — re-runs health checks, writes an incident report, updates the knowledge base, notifies your team channel (Discord/Slack if configured), and offers a "What's next?" menu.

Agents spawned

Output & artifacts

• Incident report at {project-root}/.claude/qa-knowledge/incidents/<date>-<slug>.md (created automatically after resolution) — timeline, root cause, prevention, challenge results
• Knowledge base updates: .claude/knowledge/agents/sre.md, .claude/qa-knowledge/bug-patterns.md, .claude/knowledge/skills/incident.md (classification accuracy, recurring patterns), and matching entries written to the knowledge graph via kg-write.sh for incident summaries, bug patterns, and misclassifications (if detected)
• Team notifications at each phase if Discord/Slack is configured
• Whatever the routed skill produces — e.g. a fix PR from /fix, or a verified infra fix from /sre debug

Troubleshooting

Related

• /sre — the infrastructure route; also useful standalone for health checks
• /ci-fix — the CI-failure route
• /fix — the code-bug route, with full verification pipeline
• /restart — the local-ops route
• /qa-incident — manually record a known issue without running triage

/issue

Create, close, list, and remind on GitHub issues.

Synopsis

/issue <title>, /issue close #N, /issue list, /issue status, /issue remind, /issue update #NCopy

When to use it

• Filing a quick, well-formed GitHub issue without leaving the session — it generates the task line and acceptance-criteria checkboxes for you
• Closing out finished issues, checking milestone progress, or posting a status reminder
• Capturing bugs discovered mid-task (other skills like /autopilot file issues through the same flow)
• Not for: actually working the issues — that's /autopilot for a queue or /fix for one bug

Quickstart

/issue Fix login redirect loop on SafariCopy

What you'll see: an issue created with a ## Task one-liner and 2–5 acceptance-criteria checkboxes (a short checklist of concrete conditions that define when the issue is "done"), attached to the most recent open milestone if one exists, and the issue URL reported back. If no assignee is given or inferable, it asks who to assign.

Examples

/issue Fix login bug --assign sam            # create + assign
/issue Set up CI --milestone "Launch Prep"   # create + attach to a milestone
/issue fix auth bug --assign sam, add dark mode --assign ana   # two issues at once
/issue close #270                            # close (also: /issue done #270)
/issue close #270 fixed by PR #456           # close with a reason — added to the close comment
/issue list                                  # open issues in the current milestone
/issue list sam                              # open issues assigned to sam only
/issue status                                # milestone progress: X/Y done, days remaining
/issue remind                                # post milestone status + open issues
/issue remind ana                            # reminder for one person's issues only
/issue update #270 waiting on API key        # add a comment to an issue
/issue update #270 --title "Urgent: login bug"  # retitle an issueCopy

Blank /issue (no title) prompts you interactively for what the issue should be about.

Arguments & flags

What it does

1. Parses your input — title, assignee, milestone; multiple comma- or line-separated issues are created in parallel.
2. Generates the body — a ## Task one-liner plus a ## Acceptance Criteria checklist (always included).
3. Creates via gh — gh issue create, then attaches the milestone (specified, or the most recent open one). If the assignee is ambiguous, it asks you first — user-confirmation checkpoint.
4. Reports the URL back so you can open it immediately.
5. Close / list / status / remind / update subcommands map directly onto gh issue close|list|comment|edit and the milestone API, formatted as clean tables.

Output & artifacts

• GitHub issues created, closed, commented on, or retitled in the current repository
• Issue URLs and milestone-progress tables in the conversation
• No local files written

Troubleshooting

Related

• /autopilot — works the issue queue this skill creates
• /fix — formal pipeline for a single bug issue
• /tech-debt — its findings can be filed as issues via /issue

/kb-diagram

Render the project knowledge base as an architecture diagram (Mermaid or DOT/SVG) from graph.jsonl, with optional push to connected diagramming MCPs.

Synopsis

/kb-diagram [--format=mermaid|dot] [--output=PATH] [--no-ingest] [--push <adapter>|auto] [--help]Copy

Also triggers on the phrases "architecture diagram", "kb architecture", "knowledge diagram", or "diagram knowledge" if you'd rather describe the task than type the command.

When to use it

• You want a visual map of what's in .claude/knowledge/shared/ — how conventions, domain rules, and patterns connect
• After a /calibrate run, to review the knowledge base at a glance
• Pushing the KB diagram into a connected diagramming tool (e.g. Pencil) via MCP
• Not for: diagramming topic wikis — those live under .claude/wikis/ (wiki-knowledge-base); or diagramming your application code

Quickstart

/kb-diagramCopy

What you'll see: the knowledge graph is (re)ingested from your KB files, then a Mermaid diagram is written to .claude/knowledge/diagrams/kb-architecture.mmd, clustered by node type with a legend.

Examples

/kb-diagram                      # Mermaid output (default) → .mmd
/kb-diagram --format=dot         # DOT source → .dot; SVG too if `dot` is installed
/kb-diagram --output=my-kb       # override the output file basename
/kb-diagram --no-ingest          # skip re-indexing, use existing graph.jsonl
/kb-diagram --push auto          # push to the first connected diagramming MCPCopy

Arguments & flags

What it does

1. Ingest — indexes your .claude/knowledge/shared/*.md files into the knowledge graph (graph.jsonl), unless --no-ingest is set.
2. Render — generates a Mermaid (or DOT) diagram of the graph, clustered by node type to stay readable for typical KBs (< 25 nodes). Missing KB files are marked ✗ in the legend rather than failing the run.
3. Push (optional) — with --push, sends the diagram to a connected diagramming MCP server; --push auto reports what's detected.

A PostToolUse hook also re-renders the diagram automatically in the background whenever you save a .claude/knowledge/shared/*.md file — no watch flag needed.

Output & artifacts

Troubleshooting

Note: --filter and --depth flags for very large KBs (> 40 nodes) are not yet implemented.

Related

• /calibrate — builds the knowledge base this skill diagrams
• /wiki-knowledge-base — topic wikis (research KBs) rather than the project KB

/magazine-generator

Generate a single-file HTML horizontal-swipe magazine from product metadata and brand guidelines.

Synopsis

/magazine-generator [product-name]Copy

When to use it

• Creating a visually striking product story to share with a client, prospect, or board — no designer needed
• Packaging an engagement outcome or a client's new product into a swipeable, self-contained showcase
• Not for: structured written deliverables like reports and decks — that's /deliverable-builder; or formal proposals — that's /pitch-generator

Quickstart

/magazine-generator acme-proCopy

What you'll see: a short brand questionnaire (tagline, colors, fonts, product copy), then a self-contained output/magazine-acme-pro.html — a 10-page horizontal-swipe magazine you can open in any browser, email, or host as a static asset (Google Fonts requires internet access to load; offline viewing falls back to system fonts).

Examples

/magazine-generator                 # collect all inputs interactively
/magazine-generator acme-pro        # use "acme-pro" as the product name, collect the rest
/magazine-generator acme-pro --fast # skip optional inputs, use sensible defaultsCopy

Arguments & flags

What it does

1. Reads project context (prep work, before you're asked anything) — checks .claude/knowledge/shared/domain.md and CLAUDE.md if they exist, for product description, audience, differentiators, and any documented color/font preferences. Anything found here pre-fills the questions in the next step — you won't be asked for it again.
2. Collects brand inputs — user-confirmation checkpoint: asks for tagline, primary/accent/dark-panel colors, heading and body fonts (Google Fonts), and product copy via a single AskUserQuestion prompt. Anything already known from step 1 or the argument is pre-filled. For colors/fonts, type "defaults" for a clean dark-teal + Inter combination, or paste/enter your own. Copy can be pasted, given as a file path, or synthesized with "use project context".
3. Generates the magazine — a single self-contained HTML file with 10 fixed pages, each covering one story beat: Cover, Problem, Solution, Features, Audience, Competition, Origin Story, Launch/Traction, Tech, Back Cover. Scroll-snap horizontal swipe, dot navigation, keyboard arrows, and touch gestures are built in. All CSS and JS are inline; the only external dependency is Google Fonts.
4. Quality gate — 12 checks before writing: exactly 10 pages, scroll-snap present, at least 3 dark panels, an oversized stat element, the Google Fonts link, navigation dots, keyboard handler, touch handler, no external JS libraries, all 10 page IDs present, no leaked [PLACEHOLDER] text, and no secrets in the output.
5. Writes the file and offers next steps — adjust colors, rewrite a page, change fonts, or /share the file.

Output & artifacts

• output/magazine-<product-name-slug>.html — the complete magazine (slug = product name lowercased, spaces → hyphens); the output/ directory is created if needed
• Safe to commit to a repository as a static asset; works opened directly from the filesystem (no server)

Troubleshooting

Related

• /consulting — the client-engagement suite this complements for product storytelling
• /pitch-generator — formal proposals and pitch documents instead of a visual magazine
• /deliverable-builder — structured written deliverables from engagement data
• /share — format the generated magazine for sharing

/marker

Drop a timeline marker into the current session for later A/B comparison.

Synopsis

/marker "<label>"Copy

When to use it

• Annotating meaningful moments during an A/B experiment — "starting refactor", "bug repro confirmed", "baseline recorded" — so the Arth dashboard can display them in the compare view
• Bookmarking a point in a long session you'll want to find later on the timeline
• Not for: configuring telemetry itself — that's /otel-setup

Quickstart

/marker "starting refactor"Copy

What you'll see: marker recorded: starting refactor — the marker is attached to the current session's timeline. If the Arth engine isn't reachable, you'll see marker queued (engine unreachable): starting refactor instead and the marker is saved locally.

Examples

/marker "starting refactor"      # annotate the start of an experiment arm
/marker "baseline recorded"      # mark the comparison point
/marker "bug repro confirmed"    # pin the moment a hypothesis was verifiedCopy

What it does

1. Reads the current Claude Code session ID to identify which session the marker belongs to.
2. Captures a nanosecond-precision timestamp.
3. Sends {label, timestamp_ns, session_id} to the Arth engine's markers API.
4. If the engine is unreachable, appends the marker to a local fallback file (/tmp/claude-agents-otel/<session>/markers.jsonl) instead — markers are never lost, and the skill never blocks your session.

Each invocation appends a new marker — running the same label twice records two distinct markers, so you can mark repeated checkpoints (e.g. each retry of an experiment) without overwriting earlier ones. The whole operation is inline shell with no agent spawns, so it adds effectively zero cost or latency to your session.

Output & artifacts

• A timeline marker on your session in the Arth dashboard — see Arth Intelligence for how markers appear in the session compare view
• Fallback file /tmp/claude-agents-otel/<session>/markers.jsonl when the engine is unreachable (append-only)

Troubleshooting

Related

• Arth Intelligence — the dashboard where markers show up in A/B compare views
• /otel-setup — configure the observability pipeline that feeds the dashboard

/market-research

Research industry AI adoption, competitors, and trends.

Synopsis

/market-research <client-name> [--focus industry|competitors|trends]Copy

Prerequisites

• A client profile at clients/<client-name>/profile.json (run /client-discovery first if it doesn't exist yet)
• WebSearch tool access — this skill runs live research queries and has no offline mode

When to use it

• Building the evidence base for a proposal — adoption rates, ROI benchmarks, named case studies
• Profiling what a client's competitors are doing with AI and where the gaps are
• Scanning emerging AI technology and regulatory shifts relevant to a client's vertical
• Not for: the initial client intake and maturity scoring — that's /client-discovery

Quickstart

/market-research acme-corp --focus industryCopy

What you'll see: a series of WebSearch queries, then a sourced research report — adoption landscape, case studies, ROI benchmarks, and a Porter's Five Forces AI analysis — written to the client's discovery directory.

Examples

/market-research acme-corp                     # no focus — runs all three modes sequentially (slower, ~15-25 units)
/market-research acme-corp --focus industry    # adoption rates, use cases, ROI benchmarks (fastest, single mode)
/market-research acme-corp --focus competitors # competitor AI capabilities and gaps
/market-research acme-corp --focus trends      # emerging tech, regulation, market shiftsCopy

Arguments & flags

What it does

1. Loads the client profile — reads clients/<client-name>/profile.json for industry, company name, known competitors, geography, and AI maturity. If the profile is missing, it asks you to run /client-discovery <client-name> first.
2. Executes research queries — 8 WebSearch queries per focus mode, tailored to the client's industry, competitors, and geography. Collects adoption percentages, named case studies with quantified outcomes, ROI benchmarks, and implementation barriers — all with source attribution.
3. Porter's Five Forces AI analysis — builds an AI-specific competitive forces canvas (new entrants, vendor power, customer power, substitutes, rivalry), each force rated HIGH/MEDIUM/LOW with justification and a strategic implication for the client.
4. Synthesizes findings — each insight gets supporting evidence with citation, relevance to the client, a recommended action, and a confidence rating (HIGH/MEDIUM/LOW). Cross-references identify convergent signals, contradictions, white spaces, and urgent threats.
5. Quality checklist — before output: every claim cited, ROI numbers sourced and dated, competitor data within 12 months, no speculative claims presented as facts.

Output & artifacts

Written to clients/<client-name>/discovery/ (relative to your Arth client workspace directory), one file per focus mode:

• discovery/market-research.md — industry focus: adoption landscape, case studies, ROI benchmarks, Five Forces canvas, strategic implications
• discovery/competitive-landscape.md — competitors focus: capability matrix, per-competitor profiles, gap analysis, opportunities and threats
• discovery/industry-trends.md — trends focus: near/mid/long-term trend timeline, regulatory landscape, technology watch list

All reports end with a numbered source list.

Troubleshooting

Related

• /consulting — the engagement orchestrator; research feeds the assess and propose phases
• /client-discovery — produces the client profile this skill reads
• /opportunity-map — uses research findings when scoring initiatives
• /pitch-generator — cites this research in proposals

/memory-setup

Configure arth-memory — the org decision/memory layer for AI agents. Choose Cloud (talk directly to your org's deployed server — zero local infra, best for trying it / team testing), Local (Docker store on this machine), or Global (offline replica of a central AWS/GCP server), then register the MCP server. Opt-in.

Test the org memory in ~1 minute (Cloud)

The fastest way to evaluate arth-memory — no Docker, no Ollama, nothing to run locally:

/memory-setup        # choose "Cloud" → paste your org's server URL (e.g. the ALB) → doneCopy

Then open a new session and ask an agent to do a task in a repo your org has seeded — it pulls the org's decisions/constraints via compile_context automatically. Or browse the dashboard at <server-url>/dashboard. Behind the scenes this registers the arth-memory-mcp-remote bridge, which calls the deployed REST API over HTTP.

To share with teammates: send them your toolkit branch + the server URL. They run /memory-setup → Cloud → paste the URL. That's it.

Synopsis

/memory-setupCopy

When to use it

• First-time setup: you want your coding agents to recall your team's Decisions, Constraints, and Facts (the "why") and have rule violations flagged at coding time
• Switching a machine from a standalone Local store to a shared Global (central) one, or vice versa
• Re-pointing at a different central server, or verifying an existing config still works
• Not for: running /calibrate itself — /memory-setup just configures where knowledge is stored and synced; /calibrate fills it

Quickstart

/memory-setupCopy

Pick Cloud to test your org's deployed server instantly (no local infra), Local to run an offline Docker store, or Global to replicate the central server offline. Then run /calibrate.

Examples

/memory-setup        # the only form — the skill is interactiveCopy

Typical runs:

• First time, solo/offline → choose Local → a Docker FalkorDB store starts, the MCP server is registered, the store is created at ~/.arthai/memory
• Joining an org with a central server → choose Global → provide the server URL + your reader token → an offline replica syncs down (gated at 1 GB)
• Already configured → re-run → it offers to reconfigure, or just re-verifies your existing setup

What it does

/memory-setup is fully opt-in and additive — if you never run it, the toolkit behaves exactly as today (no memory MCP server, no container).

1. Installs the arth-memory CLI if it isn't already on your PATH.
2. Asks how to connect — a user-confirmation checkpoint:

• Cloud — talk directly to your org's deployed server over HTTP (no Docker/Ollama/store). You provide its URL (+ optional reader token). Fastest to try / test.
• Local — a Docker FalkorDB store on this machine + native Ollama. Fully offline, ~$0.
• Global — an offline replica synced from your org's central AWS/GCP server (you provide its URL + a reader token).

1. Asks where the local knowledge store lives (default ~/.arthai/memory). Knowledge is more than one repo — KB/KG for every repo you work on lives in this one store, and each repo points at it via gitignored symlinks (.claude/knowledge → store). Knowledge is never committed per-repo.
2. Registers the arth-memory MCP server in .claude/settings.local.json (so agents get compile_context, constraint_check, write).
3. Runs an initial 1 GB-gated sync: under 1 GB → downloads everything into the store; larger orgs defer to selective sync (a later milestone).

Output & artifacts

• ~/.arthai/memory-configured — marker (cloud | local | remote)
• ~/.arthai/config.json — { mode, memory_dir? , api_url? } (read by the toolkit lib + context hook)
• A running store: none for Cloud (direct API); arth-memory-falkordb Docker container (Local) or arth-memory-replica (Global)
• <repo>/.claude/settings.local.json — the arth-memory MCP server block (git-ignored; reader token only)
• <repo>/.claude/{knowledge,project-profile.md,okf} — gitignored symlinks into the store

Troubleshooting

• arth-memory CLI not found after install — open a new shell so PATH updates, then re-run.
• Local: Docker not running — start Docker Desktop and re-run; the store container needs it.
• Local: recall is keyword-only — native Ollama isn't reachable; install it and pull nomic-embed-text, then re-sync.
• Global: 401 — your reader token is wrong or expired; get a fresh one from your admin.
• Global: total_live: 0 — the central store itself is empty; an admin needs to seed it (org build / first calibrate).
• Nothing changed in a repo — /memory-setup configures the machine; run /calibrate in the repo to populate/hydrate.

Related

• /calibrate — establishes the store, emits an OKF bundle, and (when memory is configured) pushes generated knowledge up / hydrates it down
• /implement, /planning, /qa — automatically read the memory store as context (injected by the toolkit's context hook)
• /otel-setup — the sibling opt-in configuration skill (observability)

/onboard

Session onboarding — project briefing, work prioritization, and guided setup.

Synopsis

/onboardCopy

When to use it

• At the start of a session, to see where things stand and what to work on
• After time away — "where did I leave off?" — to recover branch, plan, and PR context
• On a brand-new (empty) project, to get pointed at the right first steps
• Not for: deep project learning and toolkit configuration — that's /calibrate; or populating CLAUDE.md — that's /scan

Quickstart

/onboardCopy

What you'll see: any toolkit updates since your last session, then a tiered briefing — 🔴 Fix first, 🟡 Waiting on you, 🔵 Continue, ⚪ Available — with PR/issue numbers, uncommitted files, plan progress (e.g., "Step 3/5" or "Phase 2"), and a menu of available workflows. It presents and waits; it never auto-starts work.

Examples

/onboard            # the only form — behavior adapts to your project's stateCopy

What it does

1. Detects project state — greenfield (no code, no CLAUDE.md, fresh git history) vs brownfield (existing code).
2. Greenfield flow — asks one question via AskUserQuestion ("What are you building?") — a user-confirmation checkpoint — then suggests a tech stack and asks you to confirm or adjust it (user-confirmation checkpoint). It then runs /scan to scaffold CLAUDE.md, and creates a project plan via /planning if the feature is non-trivial — or scaffolds directly if it's simple enough.
3. Brownfield: toolkit update check (always first) — compares the toolkit's current version against what this project last saw and shows new commits, new skills, and updated agents. If the project has never been calibrated, it shows a /calibrate hint.
4. Deep context gathering (no questions asked) — in parallel: git state (branch, status, recent commits, stashes), GitHub state via gh (your open PRs, review requests, assigned issues, recent merges, unassigned issues), active plan files, and environment health from the CLAUDE.md ## Environments table (Docker containers, health endpoints — production is checked read-only). Also checks whether the tech-debt baseline (written by /tech-debt) is stale: if it's more than 14 days old and there have been 5+ commits since, a hint appears in the ⚪ Available tier suggesting you run /tech-debt to refresh it; if no baseline exists yet, it suggests creating one.
5. Prioritizes — weights findings by the nature of your project (production app vs early-stage vs library) and by labels (bug/critical/security → fix first; CHANGES_REQUESTED or stale PRs → waiting on you).
6. Presents the briefing — only the tiers that have items, with actionable detail (who's waiting, how long, which files, which plan step) plus the workflow menu (/planning, /fix, /qa, /pr, …).
7. Routes on your choice — picks the right skill or fix command for whatever you select. If you type something specific at any point, onboarding gets out of the way.

Output & artifacts

• The briefing itself, in the conversation — no code or config changes
• .claude/.toolkit-last-seen-sha — updated so toolkit changes are only announced once
• Greenfield path may chain into /scan (writes CLAUDE.md) or /planning

Troubleshooting

Related

• /calibrate — first-time deep project learning (onboard hints at it when missing)
• /scan — populates CLAUDE.md; onboard runs it for greenfield projects
• /welcome — the non-engineer equivalent (intent menu instead of a briefing)
• /planning — where feature work usually goes next

/opportunity-map

Map AI opportunities by ROI and effort, recommend target orgs.

Synopsis

/opportunity-map <client-name>Copy

When to use it

• After discovery, to turn pain points and readiness data into a prioritized list of AI initiatives
• Building the priority matrix and phased roadmap that anchors the proposal
• Not for: dollar-level financial modeling of an initiative — that's /roi-calculator; or gathering the underlying client data — that's /client-discovery

Quickstart

/opportunity-map acme-corpCopy

What you'll see: 8-15 candidate AI initiatives generated from the client's pain points, each scored and ranked, a 2x2 impact/effort matrix, a three-wave roadmap, and department-level recommendations written to the client's assessment directory.

Examples

/opportunity-map acme-corp     # the single invocation form — reads discovery, writes assessmentCopy

What it does

1. Loads discovery data — reads clients/<client-name>/discovery/ and profile.md; extracts pain points, goals, tech stack, readiness scores, maturity level, budget, and timeline. If discovery/intake.md, current-state.md, or maturity-assessment.md are missing, it stops and tells you to run /client-discovery first.
2. Generates AI initiatives — 8-15 candidates using Jobs-to-Be-Done framing: at least 2 per pain point, a mix of Automation / Insight / Generation / Prediction types, at least 2 quick wins and 1 moonshot, calibrated to the client's maturity level.
3. Scores every initiative — weighted formula across 6 factors: Revenue Impact (25%), Cost Savings (20%), Feasibility (20%), Time to Value (15%), Strategic Alignment (10%), Risk inverse (10%). Scores classify as Must-Do / Should-Do / Could-Do / Defer, each with a written justification.
4. Priority matrix — an ASCII 2x2 impact/effort matrix (Quick Wins, Strategic Bets, Fill-Ins, Money Pits) plus a ranked priority table.
5. Three-wave roadmap — Wave 1 Quick Wins (Month 1-2), Wave 2 Foundation Building (Month 3-4), Wave 3 Strategic Bets (Month 5-6), with deliverables, dependencies, resources, and success metrics per wave.
6. Capability mapping — maps the toolkit's actual agent ecosystem to each client department: which agents and skills deploy where, a concrete in-practice scenario, and a week-one quick win per department, plus cross-department synergies.

Output & artifacts

Written to clients/<client-name>/:

• assessment/opportunity-matrix.md — initiative catalog, factor-by-factor scoring, ASCII priority matrix, ranked table, justifications
• assessment/roadmap.md — three-wave roadmap, timeline visualization, dependencies, budget summary, KPIs, risk register per wave
• assessment/department-recommendations.md — per-department agent/skill briefs, synergies, change-management and governance recommendations

Troubleshooting

Related

• /consulting — the engagement orchestrator; runs this as the assess phase
• /client-discovery — produces the discovery data this skill requires
• /roi-calculator — next step: financial models for the top-scored initiatives
• /pitch-generator — folds the matrix and roadmap into the proposal

/otel-setup

Configure OTEL observability — starts the local Arth Intelligence Docker stack (or points at a remote endpoint) and writes the env vars.

Synopsis

/otel-setupCopy

When to use it

• First-time setup: you want your Claude Code sessions to appear on the Arth Intelligence dashboard with cost and token data
• Repairing a broken or partial OTEL config (the classic symptom: sessions show up but cost columns are empty)
• Re-pointing telemetry at a different endpoint, or verifying an existing config still works
• Not for: understanding what the dashboard shows or how the data flows — that's the Arth Intelligence guide

Quickstart

/otel-setupCopy

What you'll see: a check of your current config, then two questions — where to send traces (Cloud / Local / Custom), and how much telemetry to collect (Native-only vs Full, see below) — after which the skill writes the env vars (globally by default, so every project on the machine emits telemetry), starts the local Docker stack if you chose Local, and verifies end-to-end by sending a test span. Restart your Claude Code session and your activity appears on the dashboard.

No toolkit? The same setup ships in the Arth CLI as arth otel-setup. Install the Arth CLI first — it's gated by your GitHub repo access (no public package).

Examples

/otel-setup        # the only form — the skill takes no argumentsCopy

Typical runs:

• First time → choose Local → Docker stack starts, env vars written, test span verified
• Cost columns empty on the dashboard → re-run → it detects the partial config and offers Repair in place
• Already configured → re-run → it offers to reconfigure, or just re-verifies your existing setup

What it does

1. Detects current state — reads .claude/settings.local.json and classifies it: not configured (full setup), fully configured (offers to reconfigure or just re-verify), or partially configured — the silent-failure case, where it shows exactly which keys are missing and offers repair-in-place, full reconfigure, or cancel — a user-confirmation checkpoint.
2. Asks question 1 — where should traces go? A user-confirmation checkpoint with three options:

• Cloud — Arth Intelligence (traces go to ingest.getarth.ai; the dashboard itself lives at app.getarth.ai, where you also get your Arth project key)
• Local — a local Docker stack: it checks Docker is running, writes ~/.arthai/docker-compose.yml (Postgres + the Arth Intelligence engine + a watchtower auto-updater, all with restart: unless-stopped), starts it, and waits for the engine health check
• Custom — your own OTLP endpoint (Honeycomb, Datadog, Jaeger, …); it asks for the URL and any auth headers

1. Asks question 2 — how much telemetry? A user-confirmation checkpoint between two depths:

• Native-only (default) — just Claude Code's own OTEL: cost by model, cost by owner, tokens. Written to the global ~/.claude/settings.json so every project on the machine emits it, including non-toolkit repos and sessions launched outside a shell.
• Full — everything in Native-only, plus the toolkit's otel-telemetry hook: skill/agent attribution (skill names, lines edited), experiment auto-tags, a richer agent DAG. Choose this only if you're running the toolkit in this repo and want that extra detail.

1. Decides scope — the native block is written to the global ~/.claude/settings.json by default (every project on the machine), so this normally isn't asked. It only prompts for an override if you want this one repo pointed somewhere different, via <repo>/.claude/settings.local.json.
2. Offers "Explain this session" inline (optional, non-experimental). After the stack is healthy, /otel-setup (and arth otel-setup) ask whether to enable the dashboard's "Explain this session" AI summary — pick any provider (Anthropic, OpenAI, Gemini, Bedrock) including free local Ollama / LM Studio (LM Studio auto-detects the loaded model, e.g. qwen). It's optional; telemetry works without it. The experimental Cloud Orchestrator (calibrate/plan a repo) is configured separately — run /cloud-setup (or arth cloud-setup); it's Claude-only and needs a GitHub token + license.
3. Writes the env vars — merges the six required OTEL keys into the chosen target without overwriting your other settings, then asks one yes/no follow-up about auto-tagging sessions for arth's /experiments page (default: on).
4. Verifies end-to-end — re-reads the config and asserts all six keys landed, checks for a stale .claude/.arth-otel.env that could silently divert spans (offering one-click reconciliation), sends a test span to the endpoint the hook will actually use, and checks your existing containers will auto-restart after a reboot (offering a one-line migration if not).
5. Finishes — writes the ~/.arthai/otel-configured marker so you aren't re-prompted, and tells you to restart your Claude Code session so traces start flowing.