Setup

---
name: setup
description: Get humane working on this machine — check what the cycle needs, configure the corpus root, token base, image backend, task-export target, language and browser tool, and install the companions and generators that are missing. Diagnoses read-only first, then installs only what the user confirms. Use on a fresh machine, when a skill complains something is missing, or to see how humane is currently configured. Triggers on humane setup, set up humane, configure humane, humane doctor, "what do I need to install", "why can't it find my tokens", "check my humane install", "настрой humane".
handoffs:
  - to: jtbd
    when: the corpus root is configured but no corpus exists yet
---

# 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.

```bash
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:

```bash
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:

```bash
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

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