Setup

Announce at start: "I'm using the humane:setup skill to diagnose this machine before changing anything."

Two jobs, in this order: find out what is actually wrong, then fix only what the user agrees to fix. Never the other way round — a setup flow that installs first and reports afterwards is one that installs things nobody wanted.

scripts/humane_setup.py doctor          # read-only: config + every check + the fix for each gap
scripts/humane_setup.py config          # show resolved configuration and where each value came from
scripts/humane_setup.py config --set language=ru [--scope project]
scripts/humane_setup.py settings        # what each setting means

doctor writes nothing, installs nothing, and never asks for a key. It exits 1 only on a genuinely blocking gap; missing optional pieces exit 0, because most of the cycle works without them.

Configuration

The settings below, resolved highest-precedence first: project humane.json > ~/.humane/config.json > HUMANE_* environment > built-in default. doctor and config print the source beside every value, so "why is it using that path?" is always answerable.

Setting	Default	What depends on it
corpus_root	~/jtbd	where jtbd writes; every later skill reads it
token_base	~/design-tokens/base.tokens.json	the global brand a project layers over
image_backend	auto	which generator brand-illustrate shells out to
task_export	none	where nielsen-heuristics files findings (linear, beads, none)
language	en	the language skills speak; captured evidence is never translated
design_tool	auto	editable design-file backend for humane:prototype (auto · pencil · none). auto uses one when the host exposes it and stays on the file ladder when it does not. Not verifiable by the doctor — it is a host capability, not a binary on PATH
artifact_root	.design	where generated artifacts land — prototypes, specimens, boards, illustrations, walks, saved reviews — each named for the skill that made it (.design/prototype-dashboard.html). Separate from corpus_root because a corpus is usually personal and global while an artifact belongs beside the project. A relative value resolves against the project directory, never the working directory. See references/paths.md for the full table
browser_tool	auto	what drives a live interface in walkthrough driven mode (and the skills that cite its procedure). auto resolves the ladder in walkthrough/references/driven.md: agent-browser CLI → Playwright MCP → host browser tools → the user drives. Set explicitly to pin a rung

Project beats environment deliberately: a repo that pins its corpus root should win over a variable that happens to be exported in the shell. Set a value in the project file when it belongs to the project, and globally when it belongs to you.

A config file that will not parse is not a missing config file. If humane.json or ~/.humane/config.json exists but holds invalid JSON, every setting it should have supplied would otherwise fall through to the layer below while doctor reported source: default — the one question this layer promises to answer, answered wrongly. Instead:

• doctor and config print !! <path> exists but <reason> and mark every value suspect; config exits non-zero so a script cannot read a full table and conclude all is well.
• config --set refuses to write to an unparseable file. Merging into it would silently discard the settings it currently holds, including ones the call never mentioned. Fix or move the file first.

Step 1 — Run the doctor and read it aloud

Run doctor and walk the output with the user. Report gaps as facts, not alarms: most are optional, and the cycle degrades honestly without them.

• corpus — no bundles yet is the normal state of a new machine, not an error. The fix is to run humane:jtbd, which creates it.
• token base — only needed if they want a shared brand across projects. A single-project user never needs one.
• image backend — optional. Without it brand-illustrate still writes every prompt to prompts.md; it just cannot generate in place.
• companions — interfaces and impeccable are separate plugins humane defers to. Absent is fine; the review skills mark those domains Not reviewed rather than improvising rules they do not own.
• browser tool — optional. Without any rung of the ladder, driven walkthroughs fall back to asking the user to perform the steps, and review full mode reports the mobile tier Not reviewed. The fix the doctor prints is npm i -g agent-browser.
• humane copies — other installed copies of humane's own skills, and whether they have drifted from this checkout. See below; this is the check most likely to surprise someone.

Drift between copies

Minimize drift between copies of a skill is a named outcome of this project, and it is the one failure the method cannot catch by reading a repo. A copy that has silently lost a file is far harder to notice than one that is merely old — on the machine this check was written for, ~/.codex/skills/jtbd was missing scripts/graph.py, so Graph Mode simply did not exist on that agent and nothing said so.

The doctor enumerates the known skill roots and the registered plugin marketplace, then classifies each copy it finds:

State	Meaning
linked	a symlink back into this checkout — the good case, nothing to do
links to a different source	a symlink into another repo; two skills share one name
missing N file(s)	named explicitly, because which file is the whole point
identical for now	an independent copy that matches today and will drift the moment either side moves

A registered marketplace pins a commit, so it reports itself perfectly in sync with its own remote while sitting versions behind the repo. The check compares version and skill count against this checkout instead, which is the only comparison that catches it.

None of this blocks. Drift is reported, never auto-repaired: re-installing over a copy someone is mid-edit on would be worse than the drift.

Step 2 — Ask before configuring

Walk the settings that are still on defaults, one at a time, and only the ones that matter for what the user is doing. Do not interview someone through five questions they have no opinion on — a first-time user usually needs corpus_root confirmed and nothing else.

Claude Code extras: use AskUserQuestion for the pick-one steps (language, task_export, scope). On other agents ask in plain text.

Then write it, naming the file and scope out loud:

scripts/humane_setup.py config --set corpus_root=~/work/jtbd --scope global
scripts/humane_setup.py config --set language=ru --scope project

Step 3 — Install what they confirm

The doctor prints the exact command for every gap, and install runs those same strings — never a second recipe that can drift from them:

scripts/humane_setup.py install                 # list the fixable gaps
scripts/humane_setup.py install "browser tool"  # run one, confirming first
scripts/humane_setup.py install --all --yes     # everything, no prompts

Each command is confirmed individually; non-interactive runs refuse without --yes rather than reading piped input as consent. Fixes that are agent slash commands (/plugin …) are listed for you to run in the agent — a shell cannot. After running, install re-runs the doctor: the verdict is the doctor's, not the installer's.

Run installs only after the user says yes, one at a time, showing the command first. Each of these reaches outside the repo, and two of them need money or credentials.

Gap	Command	Note
interfaces	/plugin marketplace add jakubkrehel/skills then /plugin install interfaces@interfaces	Claude Code only — see below
impeccable	/plugin install impeccable	Claude Code only — see below
humane on another agent	npx skills add glebis/humane-agentic-design	interactive — four prompts: agents, scope, method, confirmation. Choose scope deliberately (see below)

The two companion rows are Claude Code slash commands. /plugin does not exist on other agents, and this skill does not know a non-Claude install path for either companion — do not improvise one. On another agent, report the companion as unavailable and let the review mark those domains Not reviewed; a made-up install command is worse than a named gap. | image generator | install gpt-image-2 or nano-banana into any skills dir | needs OPENAI_API_KEY or GEMINI_API_KEY | | browser tool | npm i -g agent-browser | enables driven walkthroughs and the mobile device tier; headless, no credentials | | token base | tokens setup-edit ~/design-tokens/base.tokens.json | runs the design-tokens questionnaire | | task export | install the linear or bd CLI | or set task_export=none |

On install scope. npx skills add defaults to Project, which puts a copy in ./.agents/skills. That copy will drift from a global one, and drift between copies of a skill is a known failure of this method — pick global unless the user genuinely wants this project pinned, and say which you chose.

Never store a key. If a generator needs OPENAI_API_KEY or GEMINI_API_KEY, say which variable is missing and let the user place it in their own secret store. This skill does not read, write, print, or pass keys.

Step 4 — Re-run the doctor

Verify the change rather than declaring success. Show the before/after gap count and stop. If something still fails, say so plainly with the remaining fix — doctor exiting non-zero is a result, not a reason to keep trying commands.

Guardrails

• Diagnose before you change. Always doctor first, always show output.
• Confirm every install. These commands touch directories outside the repo, cost money, or hold credentials. No silent installs, ever.
• Never handle secrets. Name the missing variable; never ask for its value.
• Absent is a valid state. Report a missing optional piece with what it would enable, not as a failure to be fixed.
• The script stays read-only. humane_setup.py diagnoses and edits its own config file — nothing else. Installs are run by the operator with the user watching, because a doctor that installs silently is a doctor you stop trusting.

Tests

cd setup && python3 -m unittest discover -s tests -v